📍 Lecture connexe : Zabbix 7 LTS en 2026 : supervision open-source en production — pour la vue d’ensemble et les arbitrages.
L’agent Zabbix 2 a été réécrit en Go en 2020 pour remplacer l’ancien agent C, avec un objectif : remplacer les exporters tiers et les scripts personnalisés par un système de plugins natifs. En 2026, l’écosystème de plugins couvre PostgreSQL, MySQL, MongoDB, Redis, Memcached, Docker, MSSQL, Oracle, MQTT, Ceph, Smart, et une vingtaine d’autres. Ce tutoriel active trois plugins majeurs (PostgreSQL, Docker, Nginx), montre la configuration concrète, et explique comment ces plugins remontent leurs métriques sans exporter externe.
Prérequis
- Une instance Zabbix 7 fonctionnelle avec un hôte Linux supervisé via Zabbix Agent 2
- Un serveur PostgreSQL 16 et/ou Docker Engine et/ou Nginx en cours d’exécution sur l’hôte
- Niveau attendu : intermédiaire
- Temps estimé : environ 75 minutes
Étape 1 — Vérifier les plugins installés
Sur Debian 12 et Ubuntu 24.04, les plugins de l’agent 2 sont distribués en paquets séparés pour éviter d’embarquer ce dont on n’a pas besoin. La liste se voit avec apt list --installed | grep zabbix-agent2-plugin sur l’hôte. Pour ajouter un plugin manquant, on installe simplement le paquet correspondant et on relance l’agent.
sudo apt install -y \
zabbix-agent2-plugin-postgresql \
zabbix-agent2-plugin-mongodb \
zabbix-agent2-plugin-mssql
sudo systemctl restart zabbix-agent2Le plugin Docker fait partie du paquet de base zabbix-agent2 ; pas besoin de paquet additionnel. Le plugin Nginx est intégré aussi, mais demande qu’on active le module stub_status côté Nginx pour que l’agent ait quelque chose à interroger.
Étape 2 — Configurer le plugin PostgreSQL
Le plugin PostgreSQL de l’agent 2 se connecte à PostgreSQL et expose les métriques via le protocole standard de l’agent. La configuration tient en deux étapes : créer un utilisateur PostgreSQL en lecture seule pour Zabbix, puis renseigner la chaîne de connexion dans la config de l’agent.
# Sur l'hôte, créer l'utilisateur de supervision
sudo -u postgres psql <<'EOF'
CREATE USER zbx_monitor WITH PASSWORD 'mot_de_passe';
GRANT pg_monitor TO zbx_monitor;
EOFLe rôle pg_monitor est un rôle prédéfini introduit en PostgreSQL 10 qui donne accès en lecture aux vues de monitoring (pg_stat_*) sans accorder d’autres privilèges. C’est le moyen le plus propre d’autoriser un agent de supervision sans surdimensionner ses droits.
Côté agent, on édite ou crée le fichier /etc/zabbix/zabbix_agent2.d/postgresql.conf :
# Le scheme accepté par le plugin est tcp:// (TCP) ou unix:// (socket Unix), pas postgres://
Plugins.PostgreSQL.Sessions.Default.Uri=tcp://localhost:5432
Plugins.PostgreSQL.Sessions.Default.User=zbx_monitor
Plugins.PostgreSQL.Sessions.Default.Password=mot_de_passe
Plugins.PostgreSQL.Sessions.Default.Database=postgresOn redémarre l’agent : sudo systemctl restart zabbix-agent2. Pour tester, on utilise la clé exposée par le plugin : zabbix_get -s 127.0.0.1 -k pgsql.ping[]. La sortie attendue est 1 si la connexion PostgreSQL fonctionne, 0 sinon.
Étape 3 — Lier le template PostgreSQL côté frontend
Dans Configuration → Hosts → l’hôte → Templates, on ajoute PostgreSQL by Zabbix agent 2. Ce template fournit 50+ items spécifiques PostgreSQL : connexions actives par database, taille de chaque database, transactions par seconde, ratio cache hit, replication lag, deadlocks, conflicts. Les triggers fournis couvrent les cas critiques : trop de connexions, lag de réplication, autovacuum bloqué.
Le template utilise des macros pour la session : {$PG.URI}, {$PG.USER}, {$PG.PASSWORD}. On les définit au niveau de l’hôte avec les valeurs réelles. Si on a configuré une session named dans le plugin (par exemple « default »), on peut référencer la session par nom plutôt que de transmettre les credentials à chaque item ; c’est plus propre.
Étape 4 — Vérifier que les métriques arrivent
Après deux à trois minutes, Latest data sur l’hôte affiche les nouvelles métriques. Les plus utiles à observer en démarrage : PostgreSQL: Number of active connections (doit être < max_connections), PostgreSQL: Cache hit ratio (idéalement > 99 %), PostgreSQL: Database size (suit la croissance), PostgreSQL: Replication lag (à surveiller en environnement maître-esclave).
Si certaines métriques restent Unsupported, c’est généralement un problème de droits : le rôle pg_monitor couvre la majorité des cas, mais quelques métriques avancées demandent des privilèges supplémentaires. Le message d’erreur de l’item indique la requête SQL bloquée.
Étape 5 — Configurer le plugin Docker
Le plugin Docker accède au socket Docker pour interroger l’API. On donne donc à l’utilisateur zabbix les droits de lire /var/run/docker.sock. Le moyen propre est de l’ajouter au groupe docker.
sudo usermod -aG docker zabbix
sudo systemctl restart zabbix-agent2Attention : ajouter un utilisateur au groupe docker lui donne effectivement des droits root sur l’hôte (l’API Docker permet de lancer un conteneur en mode privilégié qui monte le système de fichiers hôte). Sur des hôtes sensibles, on préfère un proxy Docker en lecture seule via docker-socket-proxy.
On teste : zabbix_get -s 127.0.0.1 -k docker.info. La réponse est un JSON avec la version Docker, le nombre de conteneurs, le storage driver, etc. Si l’erreur est « permission denied on socket », c’est que la modification de groupe n’a pas pris effet — un redémarrage de l’agent suffit, sinon redémarrer la session.
Étape 6 — Lier le template Docker
Configuration → Hosts → l’hôte → Templates → ajouter Docker by Zabbix agent 2. Ce template inclut une règle LLD qui découvre les conteneurs en cours d’exécution et instancie les items pour chaque conteneur (CPU, mémoire, IO, statut, healthcheck).
L’usage typique : on a 5 conteneurs sur l’hôte, après 2 minutes on voit 5 × 6 items générés par la LLD (statut, CPU, mémoire, IO net, IO disque, healthcheck). Quand on stop un conteneur, ses items entrent en mode lost ; quand on en lance un nouveau, il est automatiquement supervisé sans intervention.
Étape 7 — Configurer le plugin Nginx
Le plugin Nginx interroge le module stub_status qui expose des métriques basiques (connexions actives, requêtes traitées, requêtes par seconde). On commence par activer ce module côté Nginx en ajoutant un location dédié.
# /etc/nginx/conf.d/stub_status.conf
server {
listen 127.0.0.1:8080;
server_name localhost;
location /nginx_status {
stub_status on;
allow 127.0.0.1;
deny all;
}
}On recharge Nginx (sudo nginx -t && sudo systemctl reload nginx). On teste : curl http://127.0.0.1:8080/nginx_status doit afficher quelques lignes avec Active connections, server accepts handled requests, Reading Writing Waiting.
Côté agent, on configure la session Nginx via une macro template : {$NGINX.STUB_STATUS.URL} = http://127.0.0.1:8080/nginx_status. On ajoute le template Nginx by Zabbix agent à l’hôte ; le template lit la macro et configure les items sur cette URL.
Étape 8 — Comprendre le mode active vs passive checks
Zabbix supporte deux modes de collecte. Le mode passive (par défaut) : le serveur Zabbix initie la connexion vers l’agent sur le port 10050 à chaque collecte. Le mode active : l’agent initie la connexion vers le serveur sur le port 10051 et pousse les valeurs.
L’avantage du mode active : il fonctionne derrière un NAT ou un firewall qui n’autorise que le sortant (cas typique d’un agent dans un site distant ou un cloud privé). L’avantage du mode passive : le serveur garde le contrôle de la fréquence et peut interroger immédiatement.
Pour basculer un item en mode active, on configure son Type sur Zabbix agent (active) au lieu de Zabbix agent. Côté agent, on s’assure que ServerActive pointe vers le serveur Zabbix. Beaucoup de templates officiels utilisent active checks par défaut pour cette raison de portabilité.
Étape 9 — Mesurer l’overhead de l’agent 2
L’agent 2 est plus économe en ressources que l’ancien agent C grâce à son design en goroutines partagées. Sur un hôte typique avec 80 items collectés à intervalle 60s, l’agent consomme environ 30 à 80 Mo de RAM et moins de 1 % CPU en moyenne. Sur des hôtes constraints (Raspberry Pi, edge device), c’est négligeable.
Pour mesurer : systemctl status zabbix-agent2 affiche la consommation mémoire courante. Si l’agent grossit anormalement (au-delà de 200 Mo), c’est généralement un plugin avec une fuite ou trop d’items LLD générés ; la solution est d’isoler le plugin coupable en désactivant un par un.
Étape 10 — Désactiver les plugins inutilisés
Par défaut, l’agent 2 charge tous les plugins installés. Pour réduire la surface d’attaque et la consommation mémoire, on désactive les plugins qu’on n’utilise pas. Dans /etc/zabbix/zabbix_agent2.conf, la directive Plugins.<Name>.System.Capacity=0 désactive un plugin spécifique. Par exemple, si on n’utilise pas Memcached :
echo "Plugins.Memcached.System.Capacity=0" | \
sudo tee -a /etc/zabbix/zabbix_agent2.d/disable_unused.conf
sudo systemctl restart zabbix-agent2Cette discipline est particulièrement utile sur des hôtes industriels où on veut le minimum de code en exécution.
Étape 11 — Mettre à jour les plugins indépendamment
Une particularité utile : les plugins de l’agent 2 sont versionnés indépendamment de l’agent. On peut donc mettre à jour le plugin PostgreSQL pour bénéficier d’un correctif sans toucher à l’agent lui-même : sudo apt install --only-upgrade zabbix-agent2-plugin-postgresql. Le plugin se recharge au prochain redémarrage de l’agent.
Côté gouvernance, cette granularité permet de pousser une mise à jour de plugin en testing avant de la généraliser, ce qui réduit le risque de régression sur la flotte.
Étape 12 — Aller au-delà avec des UserParameters
Quand aucun plugin officiel ne couvre le besoin, on revient au mécanisme historique des UserParameters : un script personnalisé sur l’hôte, dont la sortie devient une métrique Zabbix. La directive UserParameter=mon.metric,/usr/local/bin/mon_script.sh dans la conf agent rend disponible la clé mon.metric.
Les UserParameters restent utiles pour des cas spécifiques métier ou pour interroger une API interne sans plugin dédié. La discipline est d’en avoir le moins possible : ils sont moins maintenables que les plugins natifs et leur sortie n’est pas typée. Pour des cas récurrents, mieux vaut écrire un vrai plugin Go en suivant le SDK officiel, qui apportera la robustesse et le typage.
Étape 13 — Plugin MongoDB et MSSQL
Le plugin MongoDB se configure de la même manière que PostgreSQL : URI de connexion, credentials d’un utilisateur en lecture seule, et template lié côté frontend. Pour MongoDB, le rôle clusterMonitor donne l’accès aux statistiques internes sans surdimensionner les droits. Pour MSSQL, on crée un login dédié avec le rôle dbcreator ou un rôle custom limité aux DMV (VIEW SERVER STATE).
# Configuration plugin MongoDB (le scheme mongodb:// est accepté par le plugin MongoDB)
cat <<'EOF' | sudo tee /etc/zabbix/zabbix_agent2.d/mongodb.conf
Plugins.MongoDB.Sessions.Default.Uri=mongodb://localhost:27017
Plugins.MongoDB.Sessions.Default.User=zbx_monitor
Plugins.MongoDB.Sessions.Default.Password=mot_de_passe
EOF
sudo systemctl restart zabbix-agent2Les templates correspondants (MongoDB by Zabbix agent 2, MSSQL by Zabbix agent 2) suivent la même logique d’usage : on les lie à l’hôte, on définit les macros de session, on observe les métriques apparaître. La cohérence d’API entre les plugins est l’une des forces de l’agent 2 : apprendre à configurer un plugin enseigne implicitement à configurer les autres.
Étape 14 — Plugin Redis et autres data stores
Le plugin Redis n’a même pas besoin d’authentification dans la majorité des cas (Redis sans password) : il suffit que l’agent puisse atteindre le port Redis (par défaut 6379). On définit la macro {$REDIS.CONN.URI} à tcp://127.0.0.1:6379, on lie le template Redis by Zabbix agent 2, c’est terminé.
Pour Redis sécurisé avec ACL et password (Redis 6+), on ajoute les credentials dans la macro de connexion ou dans une session nommée. Pour une instance Redis Sentinel, le plugin supporte la découverte automatique des nœuds esclaves via la sentinelle.
Étape 15 — Choisir entre plugin natif et exporter Prometheus
Dans l’écosystème modernisé, certains services exposent un endpoint Prometheus (/metrics) plutôt qu’une API native. Zabbix Agent 2 supporte cette source via la clé web.page.get qui télécharge l’endpoint et un préprocesseur qui parse le format Prometheus. C’est plus verbeux qu’un plugin natif mais ça couvre tous les cas où aucun plugin n’existe.
La règle empirique : si un plugin natif existe, on l’utilise (typage, performance, support officiel). Sinon, on tombe sur l’endpoint Prometheus si l’application en expose un. En dernier recours, on écrit un UserParameter ou un plugin custom Go.
Erreurs fréquentes
| Erreur | Cause | Solution |
|---|---|---|
| « Plugin X not found » au démarrage | Paquet plugin manquant sur l’hôte | Installer zabbix-agent2-plugin-X et redémarrer l’agent |
| Items PostgreSQL Unsupported avec erreur SQL | L’utilisateur n’a pas pg_monitor |
GRANT pg_monitor TO zbx_monitor; |
| Plugin Docker : « permission denied on socket » | L’utilisateur zabbix n’est pas dans le groupe docker | usermod -aG docker zabbix puis restart agent |
| Plugin Nginx renvoie une erreur 403 | Le bloc allow 127.0.0.1; deny all; bloque l’accès via une autre IP |
Ajouter l’IP de l’agent à la liste allow ou mettre l’agent en local |
| Items LLD Docker en double après upgrade plugin | Conflit entre prototypes de l’ancien et nouveau template | Synchroniser tous les hôtes liés au template, vérifier les Discovered items |
Étape 16 — Comparer agent 2 et agent 1
Pour les déploiements legacy qui tournent encore avec l’agent 1 (en C, distribué jusqu’en 5.0), la migration vers l’agent 2 vaut presque toujours le coût. Trois bénéfices concrets : système de plugins natif (au lieu de UserParameters fragiles), meilleure efficacité mémoire grâce aux goroutines (un seul process pour N plugins versus un process par check externe), et compatibilité ascendante quasi-totale (les UserParameters de l’agent 1 fonctionnent dans l’agent 2). La migration tient en quelques heures sur un parc moyen et apporte un gain mesurable en performance et maintenabilité.