Installer Zabbix Agent sur Raspberry Pi (Raspberry Pi OS)

Un Raspberry Pi sert souvent de sonde réseau, de passerelle domotique, d'afficheur ou de petit serveur de site distant : autant d'équipements qu'on oublie jusqu'à la panne. Les superviser avec Zabbix passe par l'installation d'un agent, un service léger qui collecte les métriques système. Voir la définition complète de l'agent Zabbix.

Ce guide couvre l'installation manuelle et complète sur Raspberry Pi OS 11 (Bullseye), 12 (Bookworm) et 13 (Trixie), en 32 bits comme en 64 bits.

Le plus simple : avec Logiserv

Logiserv s'appuie sur ce même moteur Zabbix et automatise l'installation. Depuis la page Agent du tableau de bord :

curl -sSL "https://www.logiserv.app/api/agent-script/linux?token=..." | sudo bash

Le script reconnaît Raspberry Pi OS 32 et 64 bits via /etc/os-release, ajoute le bon dépôt ARM, installe le paquet, génère une clé PSK unique, écrit la configuration, crée l'hôte côté serveur dans le groupe de votre parc avec les bons templates et démarre le service. Les sondes spécifiques de l'étape 5 restent à ajouter si vous en avez besoin.

Comptez 1 à 2 minutes par système avec Logiserv. L'installation manuelle détaillée ci-dessous demande 6 étapes et une dizaine de minutes par Raspberry Pi, sans compter la création de l'hôte côté serveur Zabbix. Voir la comparaison détaillée.

32 bits ou 64 bits ?

Zabbix publie un dépôt dédié à Raspberry Pi OS (raspbian) qui couvre les deux architectures. Vérifiez la vôtre :

dpkg --print-architecture

Agent 2 est disponible pour les deux et recommandé : plugins intégrés, connexion persistante unique. Ce guide l'utilise ; pour Agent 1, remplacez agent2 par agent dans les commandes et les chemins.

Prérequis

• un accès sudo (l'utilisateur créé avec Raspberry Pi Imager en dispose)
• l'adresse IP ou le nom DNS de votre serveur Zabbix
• un accès sortant vers le port 10051/TCP du serveur

Étape 1 : ajouter le dépôt officiel Zabbix

Le nom du paquet reprend la version Debian sur laquelle repose Raspberry Pi OS. Pour Bookworm (12) :

wget https://repo.zabbix.com/zabbix/7.4/release/raspbian/pool/main/z/zabbix-release/zabbix-release_latest+debian12_all.deb
sudo dpkg -i zabbix-release_latest+debian12_all.deb
sudo apt update

Pour Bullseye, remplacez debian12 par debian11 ; pour Trixie, par debian13.

Version automatique :

. /etc/os-release
wget -qO /tmp/zabbix-release.deb \
  "https://repo.zabbix.com/zabbix/7.4/release/raspbian/pool/main/z/zabbix-release/zabbix-release_latest+debian${VERSION_ID}_all.deb"
sudo dpkg -i /tmp/zabbix-release.deb
sudo apt update

Étape 2 : installer l'agent

sudo apt install -y zabbix-agent2

Le paquet crée l'utilisateur système zabbix, installe l'unité systemd et dépose la configuration dans /etc/zabbix/. L'agent consomme quelques dizaines de mégaoctets de mémoire, sans impact notable même sur un Pi Zero 2 W.

Étape 3 : configurer l'agent

sudo nano /etc/zabbix/zabbix_agent2.conf

Les directives essentielles :

# Serveur vers lequel l'agent pousse ses métriques (mode actif)
ServerActive=zabbix.example.com
 
# Doit correspondre EXACTEMENT au nom d'hôte défini côté serveur Zabbix
Hostname=rpi-atelier-01
 
LogFile=/var/log/zabbix/zabbix_agent2.log
# 1 Mo maximum, avec rotation : limite les écritures sur la carte SD
LogFileSize=1

Le piège du Hostname

Tous les Raspberry Pi installés sans personnalisation s'appellent raspberrypi. Donnez à chacun un nom unique, identique au champ « Nom d'hôte » côté serveur, sinon deux Pi se disputent le même hôte :

sudo hostnamectl set-hostname rpi-atelier-01

Mode actif plutôt que passif

Un Pi est souvent derrière une box ou un routeur de site distant. En mode actif (ServerActive=), l'agent pousse ses données vers le serveur : aucun port entrant à ouvrir, aucune redirection à configurer. Raspberry Pi OS n'active pas de pare-feu par défaut ; si vous utilisez malgré tout le mode passif (Server=), filtrez le port 10050 comme décrit dans le guide Debian.

Étape 4 : chiffrer la liaison avec une clé PSK

openssl rand -hex 32 | sudo tee /etc/zabbix/zabbix_agent2.psk > /dev/null
sudo chown zabbix:zabbix /etc/zabbix/zabbix_agent2.psk
sudo chmod 600 /etc/zabbix/zabbix_agent2.psk

Puis dans la configuration :

TLSConnect=psk
TLSAccept=psk
TLSPSKIdentity=PSK-rpi-atelier-01
TLSPSKFile=/etc/zabbix/zabbix_agent2.psk

Reportez la clé et l'identité dans l'onglet Chiffrement de l'hôte côté serveur. Une identité distincte par Raspberry Pi est nécessaire.

Étape 5 : ajouter les sondes propres au Raspberry Pi

Deux défaillances sont typiques du Raspberry Pi : la surchauffe, qui réduit la fréquence du processeur, et la sous-tension d'une alimentation trop faible, qui corrompt la carte SD. Aucune n'est couverte par les métriques Linux standard.

La température du SoC est lisible sans configuration, en millièmes de degré :

zabbix_agent2 -t vfs.file.contents[/sys/class/thermal/thermal_zone0/temp]

Pour l'état d'alimentation, créez un paramètre utilisateur :

sudo tee /etc/zabbix/zabbix_agent2.d/raspberrypi.conf > /dev/null << 'EOF'
UserParameter=rpi.throttled,vcgencmd get_throttled | cut -d= -f2
EOF
sudo usermod -aG video zabbix

vcgencmd exige l'appartenance au groupe video. La valeur renvoyée vaut 0x0 quand tout va bien ; tout autre résultat signale une sous-tension ou un bridage thermique, actuel ou passé depuis le démarrage. Côté serveur, créez les éléments rpi.throttled et vfs.file.contents[...] sur l'hôte, puis un déclencheur sur une valeur différente de 0x0 ou une température supérieure à 80 °C.

Étape 6 : démarrer et vérifier

sudo systemctl enable --now zabbix-agent2
sudo systemctl restart zabbix-agent2
sudo systemctl status zabbix-agent2

Testez des métriques localement :

zabbix_agent2 -t agent.version
zabbix_agent2 -t system.cpu.load[all,avg1]
zabbix_agent2 -t rpi.throttled

Consultez le journal :

sudo tail -f /var/log/zabbix/zabbix_agent2.log

Messages d'erreur courants

Superviser une flotte de Raspberry Pi

Au-delà de quelques unités, la configuration manuelle de chaque carte devient fastidieuse et source d'erreurs, surtout pour des Pi déployés sur des sites distants sans accès direct. Les approches classiques sont une image personnalisée préparée avec Raspberry Pi Imager ou pi-gen, Ansible, ou l'auto-enregistrement Zabbix. Toutes laissent à résoudre la clé PSK unique par appareil.

La même installation avec Logiserv

Logiserv s'appuie sur ce même moteur Zabbix et automatise l'installation. Depuis la page Agent du tableau de bord :

curl -sSL "https://www.logiserv.app/api/agent-script/linux?token=..." | sudo bash

Le script reconnaît Raspberry Pi OS 32 et 64 bits via /etc/os-release, ajoute le bon dépôt ARM, installe le paquet, génère une clé PSK unique, écrit la configuration, crée l'hôte côté serveur dans le groupe de votre parc avec les bons templates et démarre le service. Les sondes spécifiques de l'étape 5 restent à ajouter si vous en avez besoin.

Installation manuelle ou Logiserv

Systèmes reconnus

Raspberry Pi OS 32 et 64 bits

Détection automatique via /etc/os-release, dépôt ARM officiel Zabbix.

Chiffrement

PSK unique par appareil

Clé de 32 octets générée à l'enrôlement, jamais partagée entre deux hôtes.

Port entrant requis

Aucun

Mode actif : fonctionne derrière une box ou un routeur sans redirection.

Sauvegarde de configuration

Automatique

Toute configuration existante est copiée en .bak horodaté avant réécriture.

Le fonctionnement de la page Agent est détaillé dans la documentation Logiserv.

Pour aller plus loin

• Installer Zabbix Agent 2 : le guide par système — vue d'ensemble et autres OS
• Installer Zabbix Agent sur Debian — la base de Raspberry Pi OS
• Pourquoi superviser un serveur Linux — ce que la supervision détecte avant l'incident
• Surveiller l'espace disque d'un serveur — une carte SD pleine bloque tout le système
• Quelles métriques surveiller sur un serveur — construire son plan de supervision