Guide Déploiement Agent Zabbix | Supervision infogérance

Pourquoi déployer un agent Zabbix ?

L'agent Zabbix remonte les métriques système (CPU, RAM, disque, réseau, services) au serveur Zabbix central. C'est la brique de base de la supervision en infogérance : sans agent, pas d'alerte, pas de visibilité.

📊Métriques en temps réel

🚨Alertes proactives

📈Historique & tendances

⚙Découverte automatique

Agent classique vs Agent 2

Critère	Zabbix Agent (legacy)	Zabbix Agent 2
Langage	C	Go
Plugins natifs	Non	Oui (MySQL, PostgreSQL, Docker, etc.)
Vérifications concurrentes	Non (forks)	Oui (goroutines)
Compatibilité	Toutes les clés classiques	Toutes + clés spécifiques agent2
Recommandation GiGaRuN	Legacy uniquement	Standard pour tout nouveau déploiement

ℹ

Règle : Toujours déployer Zabbix Agent 2 sauf contrainte spécifique (OS trop ancien, pas de binaire disponible).

Prérequis

Accès administrateur sur la machine cible (root / Administrator)
Adresse IP du serveur Zabbix : vérifier dans Passbolt ou la CMDB
Port 10050/TCP ouvert en sortie depuis la machine cible vers le serveur Zabbix (mode passif) ou 10051/TCP (mode actif)
Hostname unique : définir avant l'installation, il servira d'identifiant dans Zabbix
Version alignée : la version de l'agent doit correspondre à la version majeure du serveur Zabbix

⚠

Convention de nommage : Le hostname Zabbix doit suivre le format CLIENT-TYPE-NOM (ex: ACME-SRV-DC01, ACME-PC-COMPTA01). Ne jamais laisser le hostname par défaut.

Installation sur Windows

📦

Source : Télécharger le MSI depuis le site officiel Zabbix, section Zabbix Agent 2, architecture amd64.

Méthode 1 — Installation MSI interactive

1

Lancer le MSI en administrateur

Clic droit sur le fichier .msi → Exécuter en tant qu'administrateur. Accepter la licence.

2

Configurer les paramètres

Renseigner les champs :

Zabbix server IP/DNS : adresse du serveur Zabbix
Agent hostname : nom unique de la machine (convention CLIENT-TYPE-NOM)
Listen port : 10050 (défaut)
Server active : même adresse que le serveur (pour les checks actifs)

3

Terminer l'installation

L'agent s'installe comme service Windows Zabbix Agent 2 et démarre automatiquement.

Méthode 2 — Installation silencieuse (déploiement en masse)

msiexec /i zabbix_agent2-7.2.0-windows-amd64.msi /qn ^
  SERVER=IP_SERVEUR_ZABBIX ^
  SERVERACTIVE=IP_SERVEUR_ZABBIX ^
  HOSTNAME=CLIENT-TYPE-NOM ^
  LISTENPORT=10050 ^
  ENABLEPATH=1 ^
  INSTALLFOLDER="C:\Program Files\Zabbix Agent 2"

✅

Astuce RMM : Cette commande peut être poussée via N-able / script GPO pour déployer sur un parc entier.

Vérification post-installation Windows

:: Vérifier que le service tourne
sc query "Zabbix Agent 2"

:: Vérifier l'écoute sur le port 10050
netstat -an | findstr 10050

:: Tester la connexion vers le serveur Zabbix
Test-NetConnection -ComputerName IP_SERVEUR_ZABBIX -Port 10051

Installation sur Linux (Debian/Ubuntu)

Ajout du dépôt et installation

# Télécharger et installer le paquet de dépôt (adapter la version)
wget https://repo.zabbix.com/zabbix/7.2/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest_7.2+ubuntu24.04_all.deb
dpkg -i zabbix-release_latest_7.2+ubuntu24.04_all.deb
apt update

# Installer Zabbix Agent 2
apt install -y zabbix-agent2 zabbix-agent2-plugin-*

Configuration

# Éditer la configuration
nano /etc/zabbix/zabbix_agent2.conf

# Paramètres à modifier :
Server=IP_SERVEUR_ZABBIX
ServerActive=IP_SERVEUR_ZABBIX
Hostname=CLIENT-TYPE-NOM
ListenPort=10050

Démarrage et activation

# Démarrer et activer au boot
systemctl enable --now zabbix-agent2

# Vérifier le statut
systemctl status zabbix-agent2

# Vérifier l'écoute
ss -tlnp | grep 10050

Installation sur Linux (RHEL/Rocky/AlmaLinux)

# Installer le dépôt (adapter la version)
rpm -Uvh https://repo.zabbix.com/zabbix/7.2/release/rhel/9/x86_64/zabbix-release-latest-7.2.el9.noarch.rpm
dnf clean all

# Installer
dnf install -y zabbix-agent2 zabbix-agent2-plugin-*

# Configurer (mêmes paramètres que Debian)
vi /etc/zabbix/zabbix_agent2.conf

# Démarrer
systemctl enable --now zabbix-agent2

Configuration avancée

Paramètres clés du fichier de configuration

Paramètre	Valeur recommandée	Description
`Server`	IP du serveur Zabbix	Autorise les checks passifs depuis ce serveur
`ServerActive`	IP du serveur Zabbix	Adresse pour les checks actifs (l'agent pousse les données)
`Hostname`	`CLIENT-TYPE-NOM`	Doit correspondre exactement au nom d'hôte dans l'interface Zabbix
`ListenPort`	`10050`	Port d'écoute de l'agent
`Timeout`	`10`	Timeout en secondes pour les checks (augmenter si réseau lent)
`EnableRemoteCommands`	`0`	Désactivé par défaut (sécurité)
`TLSConnect`	`psk`	Chiffrement de la connexion agent → serveur
`TLSAccept`	`psk`	Chiffrement des connexions serveur → agent
`TLSPSKIdentity`	`PSK_CLIENT-TYPE-NOM`	Identifiant unique de la clé PSK
`TLSPSKFile`	Chemin vers le fichier PSK	Fichier contenant la clé hexadécimale

Configuration du chiffrement PSK

🔒

Obligatoire : Tout agent en production doit communiquer en TLS/PSK. Pas de connexion en clair.

# Générer une clé PSK (32 octets = 64 caractères hex)
openssl rand -hex 32 > /etc/zabbix/zabbix_agent2.psk

# Protéger le fichier
chmod 640 /etc/zabbix/zabbix_agent2.psk
chown root:zabbix /etc/zabbix/zabbix_agent2.psk

# Ajouter dans zabbix_agent2.conf :
TLSConnect=psk
TLSAccept=psk
TLSPSKIdentity=PSK_CLIENT-TYPE-NOM
TLSPSKFile=/etc/zabbix/zabbix_agent2.psk

# Redémarrer l'agent
systemctl restart zabbix-agent2

⚠

Stocker la PSK : Copier la clé PSK dans Passbolt immédiatement après génération. La même clé doit être renseignée côté serveur dans la configuration de l'hôte Zabbix.

Configuration PSK sous Windows

:: Générer la PSK avec PowerShell
$psk = -join ((1..32) | ForEach-Object { "{0:x2}" -f (Get-Random -Maximum 256) })
$psk | Out-File -Encoding ASCII "C:\Program Files\Zabbix Agent 2\zabbix_agent2.psk"
Write-Host "PSK: $psk"

:: Ajouter dans zabbix_agent2.conf :
:: TLSConnect=psk
:: TLSAccept=psk
:: TLSPSKIdentity=PSK_CLIENT-TYPE-NOM
:: TLSPSKFile=C:\Program Files\Zabbix Agent 2\zabbix_agent2.psk

:: Redémarrer le service
net stop "Zabbix Agent 2" && net start "Zabbix Agent 2"

Règles Firewall

Windows Firewall

:: Autoriser le port 10050 en entrée (checks passifs)
netsh advfirewall firewall add rule name="Zabbix Agent 2" ^
  dir=in action=allow protocol=TCP localport=10050 ^
  remoteip=IP_SERVEUR_ZABBIX

Linux (firewalld)

firewall-cmd --permanent --add-rich-rule='rule family="ipv4" source address="IP_SERVEUR_ZABBIX" port port="10050" protocol="tcp" accept'
firewall-cmd --reload

Linux (ufw)

ufw allow from IP_SERVEUR_ZABBIX to any port 10050 proto tcp
ufw reload

🚫

Ne jamais ouvrir le port 10050 à 0.0.0.0/0. Restreindre systématiquement à l'IP du serveur Zabbix uniquement.

Enregistrement sur le serveur Zabbix

1

Créer l'hôte dans Zabbix

Dans l'interface web Zabbix : Data collection → Hosts → Create host.

Host name : identique au Hostname configuré dans l'agent
Groups : affecter au groupe client (créer si nécessaire)
Interfaces : ajouter une interface Agent avec l'IP de la machine

2

Configurer le chiffrement

Onglet Encryption :

Connections to host : PSK
Connections from host : PSK
PSK identity : PSK_CLIENT-TYPE-NOM
PSK : coller la clé hexadécimale (depuis Passbolt)

3

Appliquer les templates

Onglet Templates — lier les templates adaptés :

Windows : Windows by Zabbix agent
Linux : Linux by Zabbix agent
+ templates spécifiques : MySQL, PostgreSQL, Docker, Nginx, Apache selon les services présents

4

Vérifier la connexion

Après quelques minutes, l'indicateur de disponibilité (ZBX) doit passer au vert. Si rouge, voir la section Dépannage.

Auto-enregistrement (optionnel)

Pour les déploiements en masse, configurer l'auto-enregistrement côté serveur :

1

Créer une action d'auto-enregistrement

Alerts → Actions → Autoregistration actions → Create action. Condition : Host metadata contains GIGARUN.

2

Configurer l'agent

Ajouter dans zabbix_agent2.conf :

HostMetadata=GIGARUN-WINDOWS

ou GIGARUN-LINUX selon l'OS. Le serveur affectera automatiquement le bon template.

Dépannage

L'indicateur ZBX reste rouge / gris

Vérifications :

Le service agent tourne-t-il ? (systemctl status zabbix-agent2 / sc query "Zabbix Agent 2")
Le port 10050 est-il ouvert dans le firewall ?
Le Hostname dans la config agent correspond-il exactement à celui dans l'interface Zabbix ?
Le paramètre Server= contient-il la bonne IP ?
Les PSK correspondent-ils entre agent et serveur ?

Erreur « Cannot connect to [[IP]:10050] »

Causes fréquentes :

Firewall local bloque le port → ajouter la règle
Firewall réseau / routeur entre le serveur et l'agent → ouvrir le flux
L'agent n'écoute pas sur la bonne interface → vérifier ListenIP=0.0.0.0

Erreur TLS / PSK mismatch

Solutions :

Vérifier que TLSPSKIdentity est identique côté agent et côté serveur
Vérifier que la clé PSK est copiée sans espace ni retour chariot supplémentaire
Sous Windows, vérifier que le fichier PSK est en encodage ASCII (pas UTF-8 BOM)
Redémarrer l'agent après toute modification

L'agent ne remonte pas certaines métriques

Vérifier :

Le bon template est-il appliqué ?
L'utilisateur zabbix a-t-il les droits de lecture sur les fichiers/dossiers surveillés ?
Tester manuellement : zabbix_agent2 -t "system.cpu.load"

Logs

OS	Emplacement des logs
Linux	`/var/log/zabbix/zabbix_agent2.log`
Windows	`C:\Program Files\Zabbix Agent 2\zabbix_agent2.log`

Checklist de déploiement

Agent 2 installé et service démarré
Hostname configuré selon la convention CLIENT-TYPE-NOM
Server / ServerActive pointe vers le bon serveur Zabbix
PSK générée et stockée dans Passbolt
TLS/PSK activé dans la config agent
Firewall : port 10050 ouvert uniquement vers l'IP du serveur Zabbix
Hôte créé dans l'interface Zabbix avec PSK et templates
Indicateur ZBX vert après quelques minutes
Données reçues : vérifier dans Monitoring → Latest data

Besoin d'aide ?

📞

Support technique GiGaRuN
Problème de déploiement ou agent qui ne remonte pas ? Ouvrir un ticket avec le hostname, l'OS et le contenu du log agent.

Contacter le support