Page History

Contexte

Simple Network Management Protocol (abrégé SNMP), est un protocole de communication qui permet aux administrateurs réseau de gérer les équipements du réseau, de superviser et de diagnostiquer des problèmes réseaux et matériels à distance.

Une requête SNMP est un datagramme UDP envoyée par le manager à destination du port 161 de l'agent. L'agent répond alors au manager avec la valeur demandée.

Les traps SNMP, elles, sont émises depuis les agents SNMP vers une destination (un serveur de supervision par exemple), qui entendra ces requêtes. Pour les comprendre, ce serveur devra disposer de bases de données avec l'ensemble des informations (OID et Descripteurs) des constructeurs, ces bases sont appelées MIB. Les valeurs pourront alors être interprétées par le serveur de supervision. Ce procédé est souvent utilisé dans les routeurs pour par exemple, avertir qu’un lien vient de tomber sur l’une de ses interfaces. L’intérêt des traps SNMP est donc d'envoyer des « alertes » dès qu’une panne apparaît sans attendre que le serveur de supervision le détecte de lui même pendant une vérification dans le cadre d’un monitoring actif.

Il se peut donc que vous souhaitiez paramétrer Shinken pour récupérer et interpréter ces traps, nous vous proposons deux moyens, via le module WS Arbiter de Shinken, ou via le module Named Pipe (aussi utilisé de manière historique dans Nagios avec le fichier nagios.cmd, que nous allons utiliser via un fichier shinken.cmd).

Info
Attention : les traps SNMP doivent être utilisées dans un réseau sécurisé, car comme nous l'avons dit, la communication s'effectue en UDP, ce qui peut être utilisé par des personnes malintentionnées pour faire du DDOS ou encore propager des fausses traps.

Recevoir des Status au Format Shinken de l'extérieur

Recevoir des Status de l’extérieur se fait par l'intermédiaire du Receiver. Il faut accrocher un des 2 modules suivants sur le Receiver:

WSArbiter ( réception des statuts via API REST )
- Permets de recevoir les status de n'importe outil de transformation de trap SNMP situé n'importe ou.
- Mise en place du module, cf Module ws-arbiter ( mise en place )
NamedPipe ( réception via un fichier "passe plat" FIFO )
- Son mode de fonctionnement impose que les outils de réception des traps soit sur l'ordinateur hébergeant le Receiver.
- Mise en place du module, cf Module ws-arbiter ( mise en place )

Remarque: Nous recommandons l'utilisation du WSArbiter qui est le module que nous ferons évoluer dans le temps car il est beaucoup moins limitatif dans son fonctionnement.

Module WS-Arbiter

Le module WS-Arbiter met a disposition une API Rest qui va permettre à Shinken de recevoir les Statuts de l’extérieur.

Mise en place du module

Il faut vérifier que la définition du module est bien présente:

Dans le répertoire /etc/shinken/modules/

ouvrir le fichier ws-arbiter :

Vérifier que les paramètres correspondent à vos attentes:

Adresse de connexion

Activation du SSL

Authentification HTTP

Code Block

#===============================================================================
# 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               ws-arbiter
    # 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 authentification =========
    # You can use HTTP basic authentification method for this module.
    # If username is set to anonymous and password is commented, then
    # no authentification will be required.
    username                 shinken
    password                shinken
}

Ensuite on va accrocher le module au receiver

Ouvrir le fichier /etc/shinken/receivers/receiver-master.cfg

Ajouter le nom du module ( ws-arbiter ) à la ligne modules

modules ws-arbiter
Redémarrer l'Arbiter via la commande service shinken-arbiter restart ( pour qu'il propage cette nouvelle configuration )

Exemple de l'hôte et du check qui vont permettre de vérifier la bonne réception des traps

Dans l’interface de configuration, il faut à présent créer le check à associer à un hôte, en passif, non actif, et volatile, car si nous souhaitons recevoir une notification dès un changement d'état. L'expiration de l'état de fraîcheur doit également être paramétrée.Voici un exemple avec la syntaxe via fichiers cfg, modèle de check dédié au modèle d'hôte "TRAP-modele" :

Code Block

define service{
        service_description     TRAP
        check_command           check-host-alive
        host_name               TRAP-modele
		is_volatile             1
        passive_checks_enabled  1
		active_checks_enabled  	0
		check_freshness			1
		freshness_threshold		300
        register                0
        check_interval      	1
        retry_interval      	1
}
 
define host{
        name    				TRAP-modele
        register        		0
}

Appliquer le modèle d'hôte "TRAP-modele" à un hôte accessible sur le réseau (le paramètre "adresse" doit être rempli), par exemple un hôte "test-trap".
Note

title	Rappels sur le fonctionnement des checks passifs

La configuration de check présentée ci-dessus est celle d'un check passif. Le statut d'un check de ce type va être mis à jour manuellement via la réception de traps SNMP.

Si aucun statut n'est reçu de manière passive pour ce check au bout de 5mn, Shinken déclenche une vérification manuelle pour éviter d'avoir un statut trop ancien et non représentatif de l'état de l'élément représenté par le check. Ce comportement est configuré via les options "check_freshness" ( pour l'activation de ce comportement ), "check_command" ( pour la commande de vérification lancée par Shinken ) et "freshness_threshold" ( en secondes, 300 pour 5mn ).

Par contre, ce comportement peut entraîner des changements de statuts du check si l'intervalle d'envoi des statuts vers le check (traps SNMP dans notre exemple) est supérieur à l'intervalle définit par l'option "freshness_threshold". Il faut donc avoir conscience de ce comportement et régler la valeur de l'option "freshness_threshold" ou bien désactiver cette fonctionnalité pour ce check ("check_freshness 0").

Script interpréteur des traps

Maintenant il faut un script (plugin) qui va se charger d’interpréter les futures traps SNMP reçues pour les envoyer à Shinken (à travers le module named-pipe et le fichier shinken.cmd).
Ajouter le script suivant que l’on appellera submit_check_result_to_receiver dans le dossier des plugins Shinken (/var/lib/shinken-user/libexec/):

Code Block

#!/bin/bash

# Arguments:
# $1 = host_name (Short name of host that the service is associated with)
# $2 = svc_description (Description of the service)
# $3 = return_code (An integer that determines the state of the service check, 0=OK, 1=WARNING, 2=CRITICAL,3=UNKNOWN).
# $4 = plugin_output (A text string that should be used as the plugin output for the service check)

echocmd="/bin/echo"

CommandFile="/var/lib/shinken/shinken.cmd"

# get the current date/time in seconds since UNIX epoch
datetime=`date +%s`

# create the command line to add to the command file
cmdline="[$datetime] PROCESS_SERVICE_CHECK_RESULT;$1;$2;$3;$4"

# append the command to the end of the command file
`$echocmd $cmdline >> $CommandFile`

On le rend exécutable et on le donne à l’utilisateur Shinken :

Code Block
chown shinken:shinken /var/lib/shinken-user/libexec/submit_check_result_for_ws-arbiter chmod +x /var/lib/shinken-user/libexec/submit_check_result_for_ws-arbiter

Pour tester le script et simuler une réception d'un trap translaté au format Shinken, il suffit d’exécuter la commande suivante qui va faire passer le service en état critique :

Code Block
/var/lib/shinken-user/libexec/submit_check_result_to_receiver test-trap TRAP 2 "test envoi trap - CRITIQUE"

Info

Les arguments sont:

$1 = Le nom de la machine concerné par la trap
$2 = Le nom du service (doit correspondre au nom donnée dans la définition du service Shinken. dans mon exemple: TRAP)
$3 = Le code de retour (0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN)
$4 = Un message texte correspondant à la sortie de la commande.

Le check devrait passer en critique, et si au bout de la période du seuil de fraîcheur, aucun nouveau trap n'a été reçu, alors la commande check-host-alive fera repasser le check à OK (si bien sur l'hôte est accessible via le réseau).

Module Named Pipe

Le module Named Pipe, via le fichier "passe plat" FIFO (First In First Out) shinken.cmd, va permettre à Shinken de récupérer les entrées ou commandes externes.

Mise en place du module

Il faut rajouter la définition du module. Si elle n'est pas présente:

Dans le répertoire /etc/shinken/modules/

Copier le fichier named-pipe.cfg et modifier les droits :

Code Block
chown shinken:shinken named-pipe.cfg chmod 644 named-pipe.cfg

Ensuite on va accrocher le module au receiver

Ouvrir le fichier /etc/shinken/receivers/receiver-master.cfg
Ajouter named-pipe à la ligne modules

modules named-pipe

Redémarrer Shinken via la commande service shinken restart

Création de l'élément de supervision en configuration

Dans l’interface de configuration, il faut à présent créer le check à associer à un hôte, en passif, non actif, et volatile, car si nous souhaitons recevoir une notification dès un changement d'état. L'expiration de l'état de fraîcheur doit également être paramétrée.
- Voici un exemple avec la syntaxe via fichiers cfg, modèle de check dédié au modèle d'hôte "TRAP-modele" :

Code Block

define service{
        service_description     TRAP
        check_command           check-host-alive
        host_name               TRAP-modele
		is_volatile             1
        passive_checks_enabled  1
		active_checks_enabled  	0
		check_freshness			1
		freshness_threshold		300
        register                0
        check_interval      	1
        retry_interval      	1
}
 
define host{
        name    				TRAP-modele
        register        		0
}

Appliquer le modèle d'hôte à un hôte accessible sur le réseau (le paramètre "adresse" doit être rempli), par exemple un hôte "test-trap"
Note

title	Rappels sur le fonctionnement des checks passifs

La configuration de check présentée ci-dessus est celle d'un check passif. Le statut d'un check de ce type va être mis à jour manuellement via la réception de traps SNMP.

Si aucun statut n'est reçu de manière passive pour ce check au bout de 5mn, Shinken déclenche une vérification manuelle pour éviter d'avoir un statut trop ancien et non représentatif de l'état de l'élément représenté par le check. Ce comportement est configuré via les options "check_freshness" (pour l'activation de ce comportement), "check_command" (pour la commande de vérification lancée par Shinken) et "freshness_threshold" (en secondes, 300 pour 5mn).

Par contre, ce comportement peut entraîner des changements de statuts du check si l'intervalle d'envoi des statuts vers le check (traps SNMP dans notre exemple) est supérieur à l'intervalle définit par l'option "freshness_threshold". Il faut donc avoir conscience de ce comportement et régler la valeur de l'option "freshness_threshold" ou bien désactiver cette fonctionnalité pour ce check ("check_freshness 0").

Script interpréteur des traps

Maintenant il faut un script (plugin) qui va se charger d’interpréter les futures traps SNMP reçues pour les envoyer à Shinken (à travers le module named-pipe et le fichier shinken.cmd).
Ajouter le script suivant que l’on appellera submit_check_result dans le dossier des plugins Shinken (/var/lib/shinken-user/libexec/):

Code Block

#!/bin/bash

# Arguments:
# $1 = host_name (Short name of host that the service is associated with)
# $2 = svc_description (Description of the service)
# $3 = return_code (An integer that determines the state of the service check, 0=OK, 1=WARNING, 2=CRITICAL,3=UNKNOWN).
# $4 = plugin_output (A text string that should be used as the plugin output for the service check)

echocmd="/bin/echo"

CommandFile="/var/lib/shinken/shinken.cmd"

# get the current date/time in seconds since UNIX epoch
datetime=`date +%s`

# create the command line to add to the command file
cmdline="[$datetime] PROCESS_SERVICE_CHECK_RESULT;$1;$2;$3;$4"

# append the command to the end of the command file
`$echocmd $cmdline >> $CommandFile`

On le rend exécutable et on le donne à l’utilisateur Shinken :

Code Block
chown shinken:shinken /var/lib/shinken-user/libexec/submit_check_result_to_receiver chmod +x /var/lib/shinken-user/libexec/submit_check_result_to_receiver

Pour tester le script et simuler une réception d'un trap translaté au format Shinken, il suffit d’exécuter la commande suivante qui va faire passer le service en état critique :

Code Block
/var/lib/shinken-user/libexec/submit_check_result test-trap TRAP 2 "test envoi trap - CRITIQUE"

Info

Les arguments sont:

$1 = Le nom de la machine concerné par la trap
$2 = Le nom du service (doit correspondre au nom donnée dans la définition du service Shinken. dans mon exemple: TRAP)
$3 = Le code de retour (0=OK, 1=WARNING, 2=CRITICAL, 3=UNKNOWN)
$4 = Un message texte correspondant à la sortie de la commande.

Le check devrait passer en critique, et si au bout de la période du seuil de fraîcheur, aucun nouveau trap n'a été reçu, alors la commande check-host-alive fera repasser le check à OK (si bien sur l'hôte est accessible via le réseau)

.

Réception des TRAPS SNMP

Installation des paquets SNMPD, SNMPTRAPD et SNMPTT

Bien entendu, il faut un serveur SNMP capable de capturer les traps, ainsi que le paquet qui va les translater vers Shinken. Voici les étapes à suivre:

Installation des paquets et dépendances :

Code Block
yum install net-snmp net-snmpd-utils net-snmp-perl snmptt perl-Sys-Syslog

Note : le paquet net-snmp est pour la partie serveur, et net-snmpd-utils est pour la partie cliente afin de diagnostiquer plus rapidement des problèmes SNMP sur vos serveurs. Mais ce n'est pas obligatoire. Les paquets net-snmp-perl et snmptt permettront de translater les traps.
Pour activer le démarrage des services SNMP au démarrage du serveur avec la commande suivante :

Code Block
chkconfig --level 3 snmpd on;chkconfig --level 3 snmptrapd on

Démarrer les services snmpd et snmptrapd :

Code Block
service snmpd start;service snmptrapd start;service snmptt start

Vous pouvez alors tester de passer une requête via les outils clients SNMP, sur son propre serveur pour vérifier la bonne communication :

Code Block
snmpwalk -v 1 -c public -O e 127.0.0.1

La commande doit retourner une réponse comme par exemple :

Code Block

SNMPv2-MIB::sysDescr.0 = STRING: Linux Shinken 2.6.32-504.16.2.el6.x86_64 #1 SMP Wed Apr 22 06:48:29 UTC 2015 x86_64
SNMPv2-MIB::sysObjectID.0 = OID: NET-SNMP-MIB::netSnmpAgentOIDs.10
DISMAN-EVENT-MIB::sysUpTimeInstance = Timeticks: (31359) 0:05:13.59
SNMPv2-MIB::sysContact.0 = STRING: Root <root@localhost> (configure /etc/snmp/snmp.local.conf)
SNMPv2-MIB::sysName.0 = STRING: shinken
SNMPv2-MIB::sysLocation.0 = STRING: Unknown (edit /etc/snmp/snmpd.conf)
SNMPv2-MIB::sysORLastChange.0 = Timeticks: (64) 0:00:00.64
SNMPv2-MIB::sysORID.1 = OID: SNMP-MPD-MIB::snmpMPDMIBObjects.3.1.1
SNMPv2-MIB::sysORID.2 = OID: SNMP-USER-BASED-SM-MIB::usmMIBCompliance
SNMPv2-MIB::sysORID.3 = OID: SNMP-FRAMEWORK-MIB::snmpFrameworkMIBCompliance
SNMPv2-MIB::sysORID.4 = OID: SNMPv2-MIB::snmpMIB
SNMPv2-MIB::sysORID.5 = OID: TCP-MIB::tcpMIB
SNMPv2-MIB::sysORID.6 = OID: IP-MIB::ip
SNMPv2-MIB::sysORID.7 = OID: UDP-MIB::udpMIB
SNMPv2-MIB::sysORID.8 = OID: SNMP-VIEW-BASED-ACM-MIB::vacmBasicGroup
(...)

Interpréteur de trap SNMP

Maintenant que l’on est capable de recevoir des trap, il faut les interpréter pour dialoguer ensuite avec Shinken. Ceci s’effectue avec le paquet snmptt :

On active le debug dans le fichier /etc/snmp/snmptt.ini, histoire de voir les traps que l’on a reçues mais pas interprétées. Si vous avez mal configuré quelque chose elle arriveront dans le fichier /var/log/snmptt/snmpttunknown.log.

Code Block
unknown_trap_log_enable = 1

On ajoute ensuite les ligne suivantes dans la configuration sous /etc/snmp/snmptrapd.conf:

Code Block
disableAuthorization yes donotlogtraps no traphandle default /usr/sbin/snmptt

Ce qui veut dire :

on accepte toutes les interruptions
on ne journalise pas les interruptions reçues (c’est SNMPTT qui s’en chargera)
on traite de la même façon toutes les interruptions : avec SNMPTT

Le service snmptrapd doit être modifié pour ne pas traduire les OID, mais les laisser sous forme numérique. C’est SNMPTT qui se chargera de cette traduction. Sous CentOS, il faut éditer le fichier /etc/sysconfig/snmptrapd et ajouter l’option comme ceci:

Code Block
OPTIONS="-Lsd -p /var/run/snmptrapd.pid"

Il faut activer également le processus de capture de trap nommé snmptrapd. Ceci se fait dans le meme fichier :

Code Block
export MIBS=/usr/share/mibs TRAPDRUN=yes

On relance les deux services pour prendre en compte les modifications :

Code Block
service snmpd restart service snmptt restart

Compilation de MIB

SNMPTT a besoin de compiler les MIBs du format TXT vers un fichier de configuration. Les MIBs de CentOS se trouvent dans le dossier /usr/share/snmp/mibs/. Si vous voulez travailler avec une MIB particulière (routeur CISCO ou autre équipement) il vous faudra l’importer sur le système afin de la compiler. Cette compilation effectue l’association OID/ action à effectuer.

Pour chaque MIB, il faut compiler à l’aide de la syntaxe suivante :

Code Block
snmpttconvertmib --in=<fichier MIB> \ --out=/etc/snmp/snmptt.conf.<equipement> \ --exec='/var/lib/shinken-user/libexec/submit_check_result $r TRAP 2'

Test avec une MIB perso

On va créer une MIB de test pour pouvoir tester toute la chaîne depuis la capture de la trap jusqu’au traitement de celle ci par Shinken:

On créé notre mib dans un fichier sous /usr/share/snmp/mibs/TRAP-TEST-MIB avec le contenu suivant:

Code Block

TRAP-TEST-MIB DEFINITIONS ::= BEGIN
IMPORTS ucdExperimental FROM UCD-SNMP-MIB;
demotraps OBJECT IDENTIFIER ::= { ucdExperimental 990 }
demo-trap TRAP-TYPE
STATUS current
ENTERPRISE demotraps
VARIABLES { sysLocation }
DESCRIPTION "Trap received !"
::= 17
END

On export cette MIB

Code Block
export MIBS=+/usr/share/snmp/mibs/TRAP-TEST-MIB

On la compile en précisant notre plugin submit_check_result, c’est donc ici que ce fait la jonction avec Shinken:

Code Block
snmpttconvertmib --in=/usr/share/snmp/mibs/TRAP-TEST-MIB \ --out=/etc/snmp/snmptt.conf.test \ --exec='/var/lib/shinken-user/libexec/submit_check_result $r TRAP 2'

Ce qui doit générer un fichier de cette forme :

Code Block

EVENT demo-trap .1.3.6.1.4.1.2021.13.990.0.17 "Status Events" Normal
FORMAT Trap received ! $*
EXEC /var/lib/shinken-user/libexec/submit_check_result $r TRAP 2 "Trap received ! $*"
SDESC
Trap received !
Variables:
  1: sysLocation
EDESC

On fait prendre en compte ce fichier à la configuration globale de SNMPTT à la fin du fichier /etc/snmp/snmptt.ini en rajoutant notre fichier généré snmptt.conf.test :

Code Block
snmptt_conf_files = <<END /etc/snmp/snmptt.conf /etc/snmp/snmptt.conf.test END

On relance les services :

Code Block
service snmptt restart service snmpd restart service snmptrapd restart

Et enfin, on lance une trap de test à la main :

Code Block
snmptrap -v 1 -c public 127.0.0.1 TRAP-TEST-MIB::demotraps localhost 6 17 '' SNMPv2-MIB::sysLocation.0 s "It's a trap"

Les logs de snmptt doivent remonter la trap:

Code Block
tail /var/log/snmptt/snmptt.log Sun Feb 1 16:02:13 2015 .1.3.6.1.4.1.2021.13.990.0.17 Normal "Status Events" localhost - Trap received It's a trap

Même chose pour les log messages du système:

Code Block
tail /var/log/messages Feb 1 16:02:13 shinken snmptt[0]: .1.3.6.1.4.1.2021.13.990.0.17 Normal "Status Events" localhost - Trap received It's a trap

Le service passe alors en critique sur Shinken et vous recevez une notification.

Au bout de une minute, comme défini dans le fichier de configuration sur Shinken, le service passe de nouveau au vert en statut OK.

Vous avez plus qu’à importer vos MIBs et faire la liaison avec Shinken de la même façon que dans cet exemple.

Pour résumer, nous avons bien la chaîne suivante:

SNMPD (pour l'écoute des Traps) –> SNMPTT (pour la translation des Traps) –> Script (pour le passage au format Shinken) –> FIFO shinken.cmd (pour l'envoi de l'état du check de l'hôte dans Shinken)

Code pour utiliser ws-arbtier au lieu de named-pipe:

il faut un script (plugin) qui va se charger d’interpréter les futures traps SNMP reçues pour les envoyer à Shinken (à travers le module named-pipe et le fichier shinken.cmd).
Ajouter le script suivant que l’on appellera submit_check_result dans le dossier des plugins Shinken (/var/lib/shinken-user/libexec/):

Code Block

#!/bin/bash

# Arguments:
# $1 = host_name (Short name of host that the service is associated with)
# $2 = svc_description (Description of the service)
# $3 = return_code (An integer that determines the state of the service check, 0=OK, 1=WARNING, 2=CRITICAL,3=UNKNOWN).
# $4 = plugin_output (A text string that should be used as the plugin output for the service check)

# Beware to update user/password and shinken-srv address
curl -u user:password -X POST -d "time_stamp=$datetime&host_name=$1&service_description=$2&return_code=$3&output=$4" http://shinken-srv:7760/push_check_result

Attention à bien changer suivant votre environnement configuration:
- user et password : user et password depuis la configuration de votre module ws-arbiter
- shinken-srv: adresse de votre serveur receiver où se situe le module ws-arbiter

Page tree

Versions Compared

Old Version 6

New Version 7

Key

Contexte

Recevoir des Status au Format Shinken de l'extérieur

Module WS-Arbiter

Mise en place du module

Exemple de l'hôte et du check qui vont permettre de vérifier la bonne réception des traps

Script interpréteur des traps

Module Named Pipe

Mise en place du module

Création de l'élément de supervision en configuration

Script interpréteur des traps

Réception des TRAPS SNMP

Installation des paquets SNMPD, SNMPTRAPD et SNMPTT

Interpréteur de trap SNMP

Compilation de MIB

Test avec une MIB perso