Installer Zabbix Agent sur macOS (Mac Apple Silicon)

Un Mac mini qui sert de serveur de build, un Mac Studio de montage, une flotte de MacBook en agence : ces machines tombent en panne comme les autres, mais restent rarement supervisées. Les intégrer à 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 macOS 11 Big Sur et versions ultérieures, sur Mac Apple Silicon.

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, onglet macOS :

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

Le script vérifie que le Mac est équipé d'une puce Apple Silicon, télécharge la dernière version stable du paquet officiel, l'installe, 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.

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

Ce que Zabbix publie pour macOS

Sur macOS, l'offre de Zabbix est plus restreinte que sur Linux ou Windows :

L'agent classique collecte les mêmes métriques système que l'Agent 2 pour une supervision courante : processeur, mémoire, disques, processus, réseau.

Prérequis

• un compte administrateur (les commandes passent par sudo)
• l'adresse IP ou le nom DNS de votre serveur Zabbix
• un accès sortant vers le port 10051/TCP du serveur

Vérifiez l'architecture depuis le Terminal :

uname -m

Le résultat doit être arm64.

Étape 1 : télécharger le paquet officiel

Les paquets sont publiés sur cdn.zabbix.com, avec le numéro de version dans le nom. Pour la version 7.4.15 :

curl -fLO https://cdn.zabbix.com/zabbix/binaries/stable/7.4/7.4.15/zabbix_agent-7.4.15-macos-arm64-openssl.pkg

Remplacez 7.4.15 par la dernière version stable, listée sur la page de téléchargement des agents Zabbix. Contrairement à Linux, aucun dépôt ne vous prévient des mises à jour : notez la version installée.

Étape 2 : installer l'agent

sudo installer -pkg zabbix_agent-7.4.15-macos-arm64-openssl.pkg -target /

Le paquet :

• crée un utilisateur et un groupe système masqués zabbix
• crée le dossier de journaux /var/log/zabbix, attribué à zabbix
• installe le binaire dans /usr/local/sbin/zabbix_agentd
• dépose la configuration dans /usr/local/etc/zabbix/zabbix_agentd.conf
• enregistre le service launchd com.zabbix.zabbix_agentd, exécuté sous l'utilisateur zabbix, et le démarre aussitôt

Étape 3 : configurer l'agent

sudo nano /usr/local/etc/zabbix/zabbix_agentd.conf

Les directives essentielles :

# Serveur vers lequel l'agent pousse ses métriques (mode actif)
ServerActive=zabbix.example.com
 
# Mode actif uniquement : l'agent n'écoute sur aucun port
StartAgents=0
 
# Doit correspondre EXACTEMENT au nom d'hôte défini côté serveur Zabbix
Hostname=mac-montage-01
 
# Emplacement prévu par le paquet, accessible à l'utilisateur zabbix
LogFile=/var/log/zabbix/zabbix_agentd.log
LogFileSize=10

Commentez la ligne Server=127.0.0.1 présente par défaut : elle n'a pas de sens en mode actif. Gardez les emplacements prévus par le paquet : l'agent tournant sous zabbix, un journal déplacé dans un dossier appartenant à root l'empêcherait de démarrer.

Le piège du nom d'hôte sur Mac

Un Mac change facilement de nom : « MacBook-Pro-de-Marie.local », un nom attribué par le réseau Wi-Fi, ou un nom renuméroté (« -2 ») quand un autre appareil porte déjà le même sur le réseau. Si Hostname n'est pas fixé explicitement, les données cessent de remonter sans erreur visible.

Fixez un nom stable dans Hostname, identique au champ « Nom d'hôte » côté serveur. Pour aligner aussi le nom du Mac :

sudo scutil --set ComputerName mac-montage-01
sudo scutil --set LocalHostName mac-montage-01
sudo scutil --set HostName mac-montage-01

Pourquoi le mode actif

Un Mac portable change de réseau en permanence : bureau, domicile, partage de connexion. En mode actif (ServerActive=), c'est l'agent qui contacte le serveur : aucun port entrant à ouvrir, aucune règle à ajouter au pare-feu de macOS, et les données remontent quel que soit le réseau.

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

Le service launchd exécute l'agent sous l'utilisateur zabbix, et non sous root : la clé doit lui appartenir, sinon l'agent ne peut pas la lire.

openssl rand -hex 32 | tr -d '\n' | sudo tee /usr/local/etc/zabbix/zabbix_agentd.psk > /dev/null
sudo chown zabbix:zabbix /usr/local/etc/zabbix/zabbix_agentd.psk
sudo chmod 600 /usr/local/etc/zabbix/zabbix_agentd.psk

Le tr -d '\n' retire le retour à la ligne ajouté par openssl, source fréquente d'erreurs SSL alert number 40. Puis dans la configuration :

TLSConnect=psk
TLSAccept=psk
TLSPSKIdentity=PSK-mac-montage-01
TLSPSKFile=/usr/local/etc/zabbix/zabbix_agentd.psk

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

Étape 5 : gérer la mise en veille

C'est la particularité du Mac : un Mac en veille ne remonte plus rien. Côté serveur, la veille ressemble à une panne.

Pour un Mac qui sert de serveur (Mac mini, Mac Studio), désactivez la mise en veille système sur secteur, en laissant l'écran s'éteindre :

sudo pmset -c sleep 0
sudo pmset -c displaysleep 10
pmset -g

Pour un portable, la veille est normale : réglez plutôt côté serveur le déclencheur d'indisponibilité de l'agent (nodata) avec une durée adaptée, ou réservez les alertes aux Mac fixes pour éviter des notifications chaque soir.

Étape 6 : démarrer et vérifier

Redémarrez le service pour appliquer la configuration :

sudo launchctl kickstart -k system/com.zabbix.zabbix_agentd
sudo launchctl print system/com.zabbix.zabbix_agentd | grep state

L'état doit être running. Testez des métriques localement :

/usr/local/sbin/zabbix_agentd -t agent.version
/usr/local/sbin/zabbix_agentd -t system.cpu.load[all,avg1]
/usr/local/sbin/zabbix_agentd -t vfs.fs.size[/,pfree]

Consultez le journal, ainsi que le journal d'erreurs de launchd si le service ne démarre pas :

tail -f /var/log/zabbix/zabbix_agentd.log
cat /var/log/zabbix/zabbix_agentd-err.log

Messages d'erreur courants

Superviser une flotte de Mac

Au-delà de quelques Mac, l'installation manuelle ne tient plus, d'autant que le paquet doit être réinstallé à chaque mise à jour. L'approche classique est un outil de gestion des appareils (MDM) : Jamf Pro, Kandji, Mosyle ou Microsoft Intune déploient le .pkg et un script de configuration sur tous les Mac. Reste à générer une clé PSK unique par machine et à créer les hôtes côté serveur.

La même installation avec Logiserv

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

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

Le script vérifie l'architecture, télécharge la dernière version stable du paquet officiel en variante openssl, l'installe, génère une clé PSK unique, écrit la configuration en mode actif, crée l'hôte côté serveur dans le groupe de votre parc avec les bons templates et démarre le service launchd. Relancé plus tard, il installe la version la plus récente de l'agent et renouvelle la clé.

Installation manuelle ou Logiserv

Architecture

Apple Silicon (M1 et suivants)

Les Mac Intel sont refusés avec un message clair : Zabbix ne publie plus d'agent pour cette architecture.

Chiffrement

PSK unique par Mac

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 sur n'importe quel réseau, y compris en déplacement.

Mise à jour de l'agent

Version stable la plus récente

Résolue à la génération du script depuis cdn.zabbix.com.

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 Windows — pour les parcs mixtes Mac et PC
• Quelles métriques surveiller sur un serveur — construire son plan de supervision
• Surveiller l'espace disque d'un serveur — la panne la plus fréquente, sur Mac aussi