SNMP trap vers Canopsis¶
Réceptionne les traps SNMP, les traduit grâce à un jeu de règles et les convertit en évènements.
Info
Ce connecteur n'est disponible que dans l'édition Pro de Canopsis.
Introduction¶
Ce guide décrit la réception et la traduction de traps SNMP pour Canopsis.
Bon nombre d'équipements émettent des traps. Canopsis est en mesure de :
- les réceptionner ;
- les traduire grâce à un jeu de règles ;
- les convertir en évènements.
Ce document aborde la première étape de cette mise en œuvre.
Pour comprendre le principe complet de traitement des traps, et
notamment savoir ce qu'il adviendra des événements de type trap
générés par le connecteur, consultez également la documentation des
règles SNMP.
Émission des traps SNMP¶
L'émission des traps SNMP n'est pas traitée dans ce guide dans la mesure où cela concerne les équipements en eux-mêmes.
Il faut configurer sur les différents émetteurs l'adresse du récepteur de traps
ainsi que son port : il s'agit de l'adresse du connecteur snmp2canopsis et du
port UDP 162 (port par défaut d'un récepteur de traps SNMP).
Connecteur snmp2canopsis¶
Le connecteur snmp2canopsis porte 3 missions :
- Réceptionner les traps
- Parser les traps et les transformer en JSON
- Publier les messages JSON obtenus dans un exchange AMQP dédié sur Canopsis
Configuration¶
Fichier de configuration¶
Le fichier de configuration du connecteur est /etc/snmp2canopsis.conf.
[snmp]
ip = 0.0.0.0
port = 162
# Communautés SNMP v1/v2c acceptées
community_mode = allowlist
communities = public
# Limitation de débit par émetteur
rate_limit_per_second = 20
rate_limit_burst = 40
[amqp]
host = rabbitmq
port = 5672
user = cpsrabbit
password = canopsis
vhost = canopsis
exchange = canopsis.snmp
Droits du fichier de configuration
Le fichier peut contenir les mots de passe des utilisateurs SNMP v3 en clair. Il doit appartenir au compte qui exécute le connecteur et n'être lisible que par lui (droits 0600). Le connecteur signale au démarrage un fichier aux droits trop ouverts.
Écoute SNMP¶
La section [snmp] contient la configuration pour l'IP et le port d'écoute des traps SNMP.
Pour permettre l'écoute quelle que soit l'adresse de la machine hôte, mettre la valeur 0.0.0.0.
Par défaut le port d'écoute est le 162.
Connexion RabbitMQ¶
La section [amqp] contient la configuration pour la connexion au bus RabbitMQ.
Il faut donc vérifier que l'URL et les identifiants qui y figurent sont les bons.
La section host est à remplir avec l'IP ou le nom DNS du RabbitMQ.
Communautés SNMP v1 et v2c¶
Par défaut (community_mode = allowlist), le connecteur n'accepte que les traps v1 et v2c dont la communauté figure dans communities (valeur par défaut : public). Indiquez toutes les communautés utilisées par vos équipements, séparées par des virgules :
community_mode = allowlist
communities = public, supervision-prod
community_mode = any accepte toutes les communautés. Ne l'utilisez que temporairement, le temps de recenser les communautés en service.
SNMP v3¶
Le connecteur reçoit les traps et les informs SNMP v3, aux trois niveaux de sécurité :
| Niveau | Authentification | Chiffrement |
|---|---|---|
noAuthNoPriv |
Non (nom d'utilisateur seul) | Non |
authNoPriv |
Oui | Non |
authPriv |
Oui | Oui |
Déclarez les utilisateurs dans une section [snmpv3], puis une section [snmpv3_<nom>] par utilisateur :
[snmp]
# Identifiant de moteur local, nécessaire pour recevoir des informs
engine_id = 80004fb805a1b2c3d4e5f6
# Répertoire persistant de l'état SNMP v3 (compteur anti-rejeu)
state_dir = /connector-snmp2canopsis/etc/snmpv3-state
[snmpv3]
enabled = true
users = routeur, switch
[snmpv3_routeur]
username = routeur
security_level = authNoPriv
auth_protocol = SHA256
auth_key = phrase_secrete_authentification
engine_ids = 80004fb8054d7972747231
[snmpv3_switch]
username = switch
security_level = authPriv
auth_protocol = SHA256
auth_key = phrase_secrete_authentification
priv_protocol = AES
priv_key = phrase_secrete_chiffrement
engine_ids = 80004fb8057377697463683031
| Paramètre | Description |
|---|---|
security_level |
Niveau de sécurité de l'utilisateur, obligatoire. Le connecteur ne démarre pas s'il est absent |
auth_protocol, auth_key |
Protocole et phrase secrète d'authentification (authNoPriv et authPriv) : MD5, SHA, SHA224, SHA256, SHA384 ou SHA512. MD5 reste accepté pour les anciens équipements, mais n'est pas recommandé |
priv_protocol, priv_key |
Protocole et phrase secrète de chiffrement (authPriv uniquement) : DES, 3DES, AES (AES-128), AES192 ou AES256. DES reste accepté pour les anciens équipements, mais n'est pas recommandé. AES192 et AES256 suivent la norme : certains anciens équipements Cisco utilisent des variantes incompatibles de ces deux algorithmes, qui ne sont pas prises en charge ; utilisez alors AES |
engine_ids |
Identifiants de moteur des équipements émetteurs, séparés par des virgules. Obligatoire pour recevoir des traps authentifiés ; sans lui, seuls les informs sont reçus |
allow_wildcard |
noAuthNoPriv uniquement : accepte les traps de n'importe quel émetteur. Le nom d'utilisateur circulant en clair, à combiner avec la limitation de débit |
engine_id (section [snmp]) est l'identifiant de moteur du connecteur. Générez-le une fois, sans préfixe 0x, et ne le changez plus :
$ python3 -c "import secrets; print('80004fb805' + secrets.token_hex(6))"
Lorsqu'il est défini, placez state_dir sur un volume persistant, qui survit au redémarrage ou à la recréation du conteneur. Sous Kubernetes, utilisez un volume persistant propre au déploiement (PersistentVolumeClaim), et une seule réplique.
Pour connaître l'identifiant de moteur d'un équipement :
$ snmpget -v3 -l noAuthNoPriv -u anyuser <équipement> 1.3.6.1.6.3.10.2.1.1.0
Si l'équipement ne fait qu'envoyer des traps, démarrez le connecteur avec SNMP_DEBUG=1 et relevez msgAuthoritativeEngineId dans les journaux du message rejeté.
Toute modification des utilisateurs SNMP v3 demande un redémarrage du connecteur.
Limitation de débit et file d'attente¶
Chaque émetteur (adresse source et nom d'utilisateur) est limité à rate_limit_per_second notifications par seconde (20 par défaut), avec des pointes jusqu'à rate_limit_burst (40 par défaut). Une adresse qui dépasse sa limite rate_limit_ban_threshold fois (5) en rate_limit_ban_window secondes (60) est refusée pendant rate_limit_ban_duration secondes (300).
Les événements en attente d'envoi vers RabbitMQ sont conservés en mémoire, dans la limite de queue_maxsize (5000 par défaut). Au-delà, par exemple si RabbitMQ est indisponible, les nouveaux événements sont abandonnés et un avertissement est journalisé.
Déroulement¶
Décodage des traps¶
Une fois réceptionnés, les traps sont décodés puis transformés en JSON.
Exemple de JSON en sortie du connecteur :
{
"component": "127.0.0.1",
"connector": "snmp",
"connector_name": "snmp2canopsis",
"event_type": "trap",
"snmp_timeticks": "2350066",
"snmp_trap_oid": "1.3.6.1.6.3.1.1.5.3",
"snmp_vars": {
"1.3.6.1.2.1.2.2.1.1": "1",
"1.3.6.1.2.1.2.2.1.7": "2",
"1.3.6.1.2.1.2.2.1.8": "2"
},
"snmp_version": "1",
"snmp_pdu_type": "trap",
"source_type": "component",
"state": 3,
"state_type": 1,
"timestamp": 1440075343
}
Le connecteur ne possédant aucune MIB, snmp_trap_oid et le tableau snmp_vars
contiennent les OID des éléments sans aucune traduction.
Selon la version SNMP, l'événement contient les champs suivants :
| Champ | Version | Contenu |
|---|---|---|
snmp_version |
toutes | 1, 2c ou 3 |
snmp_pdu_type |
toutes | trap, ou inform pour une notification qui attend un acquittement (v2c et v3) |
snmp_trap_oid |
toutes | OID de la notification |
snmp_vars |
toutes | Variables de la notification, indexées par OID. En v2c et v3, l'uptime de l'émetteur y figure sous l'OID 1.3.6.1.2.1.1.3.0 |
snmp_timeticks |
v1 | Uptime de l'émetteur |
snmp_security_name |
v3 | Nom de l'utilisateur SNMP v3 |
snmp_security_level |
v3 | Niveau de sécurité : noAuthNoPriv, authNoPriv ou authPriv |
snmp_context_engine_id, snmp_context_name |
v3 | Identifiant de moteur et nom du contexte SNMP v3 |
Ces champs peuvent servir dans les règles SNMP ou les filtres d'événements, par exemple pour traiter différemment les notifications non authentifiées (snmp_security_level égal à noAuthNoPriv).
Exemple d'événement pour un trap SNMP v3 authPriv :
{
"connector": "snmp",
"connector_name": "snmp2canopsis",
"event_type": "trap",
"source_type": "component",
"state": 3,
"state_type": 1,
"component": "172.18.0.1",
"timestamp": 1789381187,
"snmp_version": "3",
"snmp_pdu_type": "trap",
"snmp_trap_oid": "1.3.6.1.6.3.1.1.5.3",
"snmp_vars": {
"1.3.6.1.2.1.1.3.0": "51648693",
"1.3.6.1.6.3.1.1.4.1.0": "1.3.6.1.6.3.1.1.5.3",
"1.3.6.1.4.1.99999.1": "V3_AUTHPRIV_TRAP"
},
"snmp_security_name": "privlevel",
"snmp_security_level": "authPriv",
"snmp_context_engine_id": "0x80001f8880499cd15242caa76a00000000",
"snmp_context_name": ""
}
On remarque que le connecteur produit une structure JSON qui rappelle le format
des évènements Canopsis. Notons le type d'évènement (event_type) : trap.
Publication du JSON¶
Les traps transformés en JSON sont publiés dans le bus AMQP de Canopsis, dans
un exchange dédié : canopsis.snmp.
Suite du traitement¶
Ces messages (évènements de type trap) seront traduits ultérieurement en
évènements de type check, par le moteur snmp de Canopsis.
Exécution¶
Nous utilisons généralement un conteneur Docker pour cette étape.
Avec Docker Compose, par exemple dans le fichier docker-compose.override.yml de l'environnement de référence :
volumes:
cat-connector-snmp2canopsis-data:
driver: local
services:
connector-snmp2canopsis:
image: ${DOCKER_REPOSITORY}${CPS_EDITION}/connector-snmp:${CANOPSIS_SNMP_TAG}
ports:
- "162:162/udp"
volumes:
- cat-connector-snmp2canopsis-data:/connector-snmp2canopsis/etc/
- ./conf/snmp2canopsis.conf:/etc/snmp2canopsis.conf
restart: unless-stopped
Définissez CANOPSIS_SNMP_TAG dans le fichier .env avec la version du connecteur à utiliser.
Compte non root
L'image s'exécute avec un compte non root (UID/GID 10001). Le fichier de configuration monté depuis l'hôte doit être lisible par ce compte, sans être lisible par tous :
# chown 10001:10001 ./conf/snmp2canopsis.conf
# chmod 0600 ./conf/snmp2canopsis.conf
Pour SNMP v3, state_dir = /connector-snmp2canopsis/etc/snmpv3-state utilise le volume persistant cat-connector-snmp2canopsis-data.
En installation par paquets, le connecteur demande Python 3.12 ou plus récent et s'exécute avec un compte système dédié, snmp2canopsis, propriétaire du répertoire d'installation et du fichier de configuration.
$ docker run -v snmp2canopsisdata:/connector-snmp2canopsis/etc \
docker.canopsis.net/docker/pro/canopsis-pro-connector-snmp:v22.10.1
[2023-09-21 09:18:06.700607] INFO: snmp2canopsis: Read configuration from /connector-snmp2canopsis/etc/snmp2canopsis.conf
[2023-09-21 09:18:06.701409] DEBUG: amqp: Thread started
[2023-09-21 09:18:06.702131] INFO: amqp: Connecting to cpsrabbit@rabbitmq, on canopsis
[2023-09-21 09:18:06.701857] INFO: snmp: Start SNMP listener on 0.0.0.0:162
[2023-09-21 09:18:06.707382] DEBUG: amqp: Read the snmp queue
La configuration associée est la suivante :
[snmp]
ip = 0.0.0.0
port = 162
[amqp]
host = rabbitmq
port = 5672
user = cpsrabbit
password = canopsis
vhost = canopsis
exchange = canopsis.snmp
Test de fonctionnement¶
Afin de valider le fonctionnement, nous pouvons générer un trap SNMP depuis une machine.
Nous aurons besoin de la commande snmptrap.
Pour installer cette commande sous Debian :
# apt install snmp
Pour installer cette commande sous EL (RHEL/Rocky Linux/AlmaLinux/…) :
# yum install net-snmp-utils
Pour le test, nous allons nous appuyer sur la MIB Nagios
NAGIOS-NOTIFY-MIB et sa dépendance NAGIOS-ROOT-MIB.
Les deux fichiers sont à récupérer dans le dépôt GitHub nagios-plugins/nagios-mib.
Les deux fichiers récupérés doivent être placés dans le répertoire des MIB
SNMP : /usr/share/snmp/mibs.
Puisqu'il s'agit de traps SNMP, il faut s'intéresser au type NOTIFICATION TYPE présent dans les MIB.
Pour notre trap de test, nous allons utiliser l'objet nSvcEvent :
nSvcEvent NOTIFICATION-TYPE
OBJECTS { nHostname, nHostStateID, nSvcDesc, nSvcStateID, nSvcAttempt,
nSvcDurationSec, nSvcGroupName, nSvcLastCheck, nSvcLastChange,
nSvcOutput }
STATUS current
DESCRIPTION
"The SNMP trap that is generated as a result of an event with the service
in Nagios."
::= { nagiosNotify 7 }
Voici la ligne de commande utilisée avec snmptrap pour générer le trap :
snmptrap -v 2c -c public ${IP_RECEPTEUR} '' NAGIOS-NOTIFY-MIB::nSvcEvent \
nHostname s "Equipement Impacte" \
nSvcDesc s "Ressource Impactee" \
nSvcStateID i 2 \
nSvcOutput s "Message de sortie du trap SNMP"
Le connecteur reçoit ce trap, le convertit en JSON et le transmet à Canopsis
dans l'exchange canopsis.snmp.
Le JSON produit par le connecteur peut être vérifié dans les logs du service
ou conteneur snmp2canopsis. Exemple de log :
[2019-06-20 08:27:44.754789] INFO: snmp2canopsis: Read configuration from /etc/snmp2canopsis.conf
[2019-06-20 08:27:44.791038] INFO: snmp: Trap debug enabled
[2019-06-20 08:27:44.791343] DEBUG: amqp: Thread started
[2019-06-20 08:27:44.791476] INFO: amqp: Connecting to cpsrabbit@rabbitmq, on canopsis
[2019-06-20 08:27:44.919838] DEBUG: amqp: Read the snmp queue
[2019-06-20 08:27:44.920357] INFO: snmp: Start SNMP listener on 0.0.0.0:162
[2022-10-11 12:08:17.110603] DEBUG: snmp: {"snmp_version": "2c", "event_type": "trap", "timestamp": 1665490097.110236, "component": "172.20.0.1", "state_type": 1, "source_type": "component", "snmp_trap_oid": "1.3.6.1.4.1.20006.1.7", "snmp_vars": {"1.3.6.1.2.1.1.3.0": "278844995", "1.3.6.1.4.1.20006.1.3.1.17": "Message de sortie du trap SNMP", "1.3.6.1.6.3.1.1.4.1.0": "1.3.6.1.4.1.20006.1.7", "1.3.6.1.4.1.20006.1.1.1.2": "Equipement Impacte", "1.3.6.1.4.1.20006.1.3.1.6": "Ressource Impactee", "1.3.6.1.4.1.20006.1.3.1.7": "2"}, "connector": "snmp", "state": 3, "connector_name": "snmp2canopsis"}
Tester SNMP v3¶
Pour tester SNMP v3, déclarez un utilisateur par niveau de sécurité. Exemple de configuration de test :
[snmp]
ip = 0.0.0.0
port = 162
engine_id = 80004fb805a1b2c3d4e5f6
state_dir = /connector-snmp2canopsis/etc/snmpv3-state
[snmpv3]
enabled = true
users = noauth_device, authlevel, privlevel
[snmpv3_noauth_device]
username = noauth_device
security_level = noAuthNoPriv
engine_ids = 8000000001020304
[snmpv3_authlevel]
username = authlevel
security_level = authNoPriv
auth_protocol = SHA256
auth_key = authpassphrase
engine_ids = 8000000001020304
[snmpv3_privlevel]
username = privlevel
security_level = authPriv
auth_protocol = SHA256
auth_key = authpassphrase
priv_protocol = AES
priv_key = privpassphrase
engine_ids = 8000000001020304
Un trap SNMP v3 porte l'identifiant de moteur de l'émetteur, passé à snmptrap par l'option -e : il doit figurer dans engine_ids de l'utilisateur, sinon le trap est rejeté. Exemple de trap authPriv :
snmptrap -v3 \
-e 0x8000000001020304 \
-l authPriv -u privlevel \
-a SHA-256 -A authpassphrase \
-x AES -X privpassphrase \
${IP_RECEPTEUR}:162 '' \
1.3.6.1.6.3.1.1.5.3 \
1.3.6.1.4.1.99999.1 s 'V3_AUTHPRIV_TRAP'
Un inform n'a pas besoin de l'option -e : l'émetteur découvre l'identifiant de moteur du connecteur (engine_id). Exemple d'inform authNoPriv :
snmpinform -v3 \
-l authNoPriv -u authlevel \
-a SHA-256 -A authpassphrase \
udp:${IP_RECEPTEUR}:162 '' \
1.3.6.1.6.3.1.1.5.3 \
1.3.6.1.4.1.99999.1 s 'V3_AUTHNOPRIV_INFORM'
L'événement reçu est visible dans les journaux du connecteur ; un inform y apparaît avec "snmp_pdu_type": "inform".
Les cas suivants ont été validés avec cette configuration :
| Envoi | noAuthNoPriv |
authNoPriv |
authPriv |
|---|---|---|---|
Trap SNMP v3 (snmptrap -v3) |
Reçu | Reçu | Reçu |
Inform SNMP v3 (snmpinform -v3) |
Reçu | Reçu | Reçu |
Les traps SNMP v1 (snmptrap -v1) et v2c (snmptrap -v2c) de la communauté public sont reçus avec la même configuration.
Suite¶
Afin d'être transformés en évènements Canopsis susceptibles de créer ou mettre à jour des alarmes, les traps doivent encore faire l'objet d'un traitement spécifique.
Deux cas sont possibles :
- Les traps « standard » peuvent faire l'objet de règles de traitement grâce à des MIB ;
- Les traps « non standard » ou traps pour lesquels vous ne possédez pas les MIB peuvent être traités avec du code personnalisé.
Se référer à la documentation sur les règles SNMP qui détaille ces parties de la mise en œuvre.