Zabbix Agent 2 installieren: Ubuntu, Debian, Proxmox, Docker und OpenWrt

Der Zabbix-Server aus dem letzten Teil sieht nur sich selbst. Für alles andere braucht er einen Agent auf dem Zielsystem oder ein Protokoll wie SNMP. In diesem Artikel geht es um den Agent, und zwar um den Agent 2, den ich inzwischen auf 15 Maschinen laufen habe: Ubuntu, Debian, zwei Proxmox-Hosts, einem Unraid-Server als Docker-Container und einem OpenWrt-Router, auf dem es eigentlich gar keinen Zabbix-Agent gibt.

Agent oder Agent 2?

Es gibt zwei Agents. Der klassische zabbix_agentd ist in C geschrieben und existiert seit den Anfängen. Der Agent 2 ist in Go geschrieben, hat eingebaute Plugins für Docker, MySQL, PostgreSQL, Redis, systemd, Zertifikate und einiges mehr, und kann mehrere Checks parallel ausführen. Für neue Installationen nimmt man Agent 2. Punkt.

Der klassische Agent hat nur noch einen Vorteil: Es gibt ihn als statisch gelinkte Binärdatei, die auf praktisch jedem Linux läuft, auch auf OpenWrt und anderen musl-Systemen. Dazu am Ende mehr.

Aktiv oder passiv?

Das ist die wichtigste Entscheidung und wird in den meisten Anleitungen übergangen.

Passiv heißt: Der Server verbindet sich zum Agent auf Port 10050 und fragt Werte ab. Der Agent muss also vom Server aus erreichbar sein. Das funktioniert im eigenen Netz, aber nicht hinter NAT und nicht, wenn der Server irgendwo im Internet steht und der Host zuhause.

Aktiv heißt: Der Agent verbindet sich zum Server auf Port 10051, holt sich seine Liste an Checks und schickt die Ergebnisse. Der Agent braucht keinen offenen Port. Das funktioniert hinter jedem NAT, jedem Router, jeder Firewall, solange der Host nach draußen darf.

Ich nutze fast ausschließlich aktive Checks. Mein Unraid steht hinter einer Fritzbox-artigen Situation, der Server in Hetzner. Passiv käme der Server dort nie an. Die Zabbix-Templates gibt es für beide Varianten, der Name verrät es: „Linux by Zabbix agent“ ist passiv, „Linux by Zabbix agent active“ ist aktiv.

Ein Agent kann beides gleichzeitig. In der Konfiguration gibt es Server= für passiv (von wem Anfragen angenommen werden) und ServerActive= für aktiv (zu wem sich der Agent verbindet).

Installation auf Ubuntu und Debian

Repository wie beim Server einbinden, dann nur ein Paket:

wget https://repo.zabbix.com/zabbix/7.4/release/ubuntu/pool/main/z/zabbix-release/zabbix-release_latest_7.4+ubuntu24.04_all.deb
sudo dpkg -i zabbix-release_latest_7.4+ubuntu24.04_all.deb
sudo apt update
sudo apt install zabbix-agent2

Für Debian 12 ist es zabbix-release_latest_7.4+debian12_all.deb, für Proxmox 8 ebenfalls, weil Proxmox 8 auf Debian 12 basiert. Für Proxmox mit Enterprise-Repository ohne Subscription meldet apt update einen 401-Fehler für das Proxmox-Repo. Das ist egal, die Zabbix-Pakete werden trotzdem gefunden.

Nicht zabbix-agent2-plugin-* mit Wildcard installieren. Das zieht das NVIDIA-Plugin mit, und ohne NVIDIA-Treiber startet der Agent dann gar nicht mehr. Die Fehlermeldung lautet „NVML Shared Library couldn’t be found“. Ich habe eine Viertelstunde gebraucht, bis ich verstanden habe, dass der Agent wegen einer Grafikkarte streikt, die es nicht gibt. Nur die Plugins installieren, die man braucht: zabbix-agent2-plugin-postgresql für PostgreSQL, sonst nichts. MySQL, Docker, Redis und systemd sind eingebaut.

Konfiguration

Die Hauptdatei /etc/zabbix/zabbix_agent2.conf lasse ich unangetastet und lege eine eigene Datei im Include-Verzeichnis an. Das überlebt Paket-Updates.

sudo nano /etc/zabbix/zabbix_agent2.d/99-monitoring.conf

Server=203.0.113.10
ServerActive=203.0.113.10
Hostname=webserver1
RefreshActiveChecks=60

Dazu in der Hauptdatei die Standardwerte auskommentieren, sonst gibt es Konflikte:

sudo sed -i 's/^Server=127.0.0.1/# Server=127.0.0.1/; s/^ServerActive=127.0.0.1/# ServerActive=127.0.0.1/; s/^Hostname=Zabbix server/# Hostname=Zabbix server/' /etc/zabbix/zabbix_agent2.conf

Der Hostname muss exakt so heißen wie der Host später in Zabbix. Groß- und Kleinschreibung zählt. Das ist der häufigste Fehler überhaupt: Der Agent meldet sich, und im Serverlog steht „host [webserver1] not found“, weil der Host in Zabbix „Webserver1″ heißt oder noch gar nicht existiert.

Die Datei muss für den Agent lesbar sein. Wer sie mit einer restriktiven umask anlegt, bekommt „permission denied“ beim Start. chmod 644 darauf, fertig. Auch das ist mir passiert.

sudo systemctl enable --now zabbix-agent2
sudo systemctl restart zabbix-agent2
sudo tail -n 5 /var/log/zabbix/zabbix_agent2.log

Host in Zabbix anlegen

Der Agent allein bewirkt nichts. In Zabbix unter Data collection → Hosts → Create host:

• Host name: exakt der Wert aus Hostname=
• Templates: „Linux by Zabbix agent active“
• Host groups: Linux servers
• Interfaces: Bei rein aktiven Checks braucht man eigentlich keins, aber für Ping-Checks und das ICMP-Template eine Agent-Schnittstelle mit der IP des Hosts anlegen.

Nach ein bis zwei Minuten kommen die ersten Werte. Unter Monitoring → Latest data sieht man sie.

Wer viele Hosts hat, lässt Zabbix das selbst machen. Unter Alerts → Actions → Autoregistration actions legt man eine Regel an: Jeder unbekannte Agent, der sich meldet, wird als Host angelegt, bekommt das Linux-Template und landet in einer Gruppe. Dann ist die Installation des Agents der einzige manuelle Schritt.

Verschlüsselung mit PSK

Wenn Agent und Server über das Internet reden, sollte das verschlüsselt sein. Zabbix kann Zertifikate oder Pre-Shared Keys. PSK ist in fünf Minuten eingerichtet.

Einen Schlüssel erzeugen:

openssl rand -hex 32 | sudo tee /etc/zabbix/zabbix_agent2.psk
sudo chown zabbix:zabbix /etc/zabbix/zabbix_agent2.psk
sudo chmod 640 /etc/zabbix/zabbix_agent2.psk

In die Agent-Konfiguration:

TLSConnect=psk
TLSAccept=psk
TLSPSKIdentity=webserver1
TLSPSKFile=/etc/zabbix/zabbix_agent2.psk

Im Host in Zabbix unter dem Reiter Encryption: Connections to host → PSK, Connections from host → PSK, PSK identity webserver1, PSK value der Inhalt der Datei. Agent neu starten. Ab jetzt ist der Agent-Port auch dann sicher, wenn er öffentlich erreichbar ist, denn ohne den Schlüssel antwortet der Agent nicht.

Hosts, die mit öffentlicher IP und ohne VPN angebunden sind, laufen bei mir genau mit dieser Konfiguration. Alle Hosts, die ich über Tailscale erreiche, laufen unverschlüsselt, weil Tailscale selbst schon verschlüsselt.

Docker überwachen

Das Docker-Plugin ist im Agent 2 enthalten. Es braucht nur Zugriff auf den Docker-Socket:

sudo usermod -aG docker zabbix
sudo systemctl restart zabbix-agent2

Dann das Template „Docker by Zabbix agent 2″ an den Host hängen. Zabbix findet alle Container, überwacht CPU, RAM, Netzwerk und vor allem den Health-Status. Bei mir hat das Template am ersten Tag einen Container gefunden, der seit Wochen in einer Neustart-Schleife hing, ohne dass es jemand gemerkt hatte.

Datenbanken: PostgreSQL und MySQL

Beide Plugins brauchen einen Datenbankbenutzer mit Leserechten. Ich lege ihn nicht in die Template-Makros, sondern als benannte Session in die Agent-Konfiguration. Dann steht das Passwort nur auf dem Host.

PostgreSQL:

CREATE ROLE zabbix_mon LOGIN PASSWORD 'geheim';
GRANT pg_monitor TO zabbix_mon;

In pg_hba.conf eine Zeile host all zabbix_mon 127.0.0.1/32 scram-sha-256, dann SELECT pg_reload_conf();.

Agent-Konfiguration, jede Zeile einzeln:

Plugins.PostgreSQL.Sessions.Main.Uri=tcp://127.0.0.1:5432
Plugins.PostgreSQL.Sessions.Main.User=zabbix_mon
Plugins.PostgreSQL.Sessions.Main.Password=geheim
Plugins.PostgreSQL.Sessions.Main.Database=postgres

Dazu zabbix-agent2-plugin-postgresql installieren. Im Host das Template „PostgreSQL by Zabbix agent 2″ und das Makro {$PG.CONNSTRING.AGENT2} auf Main setzen. Das Makro heißt in 7.4 so und nicht mehr {$PG.URI}, was mich eine Runde gekostet hat.

MySQL und MariaDB analog:

CREATE USER 'zabbix'@'127.0.0.1' IDENTIFIED BY 'geheim';
GRANT USAGE, REPLICATION CLIENT, PROCESS, SHOW DATABASES, SHOW VIEW ON *.* TO 'zabbix'@'127.0.0.1';

Plugins.Mysql.Sessions.Local.Uri=tcp://127.0.0.1:3306
Plugins.Mysql.Sessions.Local.User=zabbix
Plugins.Mysql.Sessions.Local.Password=geheim

Template „MySQL by Zabbix agent 2″, Makro {$MYSQL.DSN} auf Local.

Prüfen kann man die Session direkt auf dem Host:

sudo zabbix_agent2 -t 'pgsql.ping[Main]'
sudo zabbix_agent2 -t 'mysql.ping[Local]'

Kommt [s|1] zurück, passt alles.

systemd-Dienste überwachen

Das Template „Systemd by Zabbix agent 2″ erkennt alle Dienste und meldet, wenn einer ausfällt oder neu startet. Ohne Filter meldet es auch jeden Timer und jeden Oneshot-Dienst, was zu einer Flut führt. Deshalb pro Host das Makro {$SYSTEMD.NAME.SERVICE.MATCHES} setzen, zum Beispiel für einen Mailserver:

^(postfix@-|dovecot|nginx|mariadb|fail2ban|ssh).service$

Und {$SYSTEMD.NAME.SERVICE.NOT_MATCHES} auf ^$, weil der Standardwert sonst dazwischenfunkt.

Genau so hätte ich meinen dreiwöchigen Postfix-Ausfall auf dem zentralen Mailserver sofort gefunden. Übrigens: Bei Postfix heißt der echte Dienst po*****@*.service. Der Dienst postfix.service ist nur ein Platzhalter und steht immer auf „active“, auch wenn nichts läuft.

Agent auf Unraid

Unraid ist Slackware ohne Paketmanager, dafür mit Docker. Der offizielle Container zabbix/zabbix-agent2 tut es. In der Unraid-Oberfläche einen Container mit Netzwerk „host“ anlegen, Variablen ZBX_HOSTNAME und ZBX_SERVER_HOST setzen, und unbedingt eine Restart-Policy. Mein erster Agent-Container hatte keine und wäre nach dem nächsten Reboot weg gewesen.

Wer Docker auf Unraid überwachen will, hängt zusätzlich /var/run/docker.sock in den Container. Die Bind-Mounts, die Docker in den Container legt (/etc/hosts, /etc/resolv.conf), tauchen dann als Dateisysteme auf und lösen „Space is low“ aus. Das Makro {$VFS.FS.FSNAME.NOT_MATCHES} um /etc/(resolv.conf|hostname|hosts)$ erweitern, dann ist Ruhe.

Agent auf OpenWrt und anderen Exoten

Für OpenWrt gibt es in manchen Feeds ein Paket, auf meinem OpenMPTCProuter aber nicht. Die Lösung ist der klassische Agent als statische Binärdatei von zabbix.com. Unter https://cdn.zabbix.com/zabbix/binaries/stable/7.4/ liegt pro Version ein zabbix_agent-7.4.x-linux-3.0-amd64-static.tar.gz. Darin ist sbin/zabbix_agentd, 2,3 MB, läuft auf jedem x86-64-Linux ohne Abhängigkeiten.

Nach /usr/sbin/ kopieren, eine Konfiguration nach /etc/zabbix/zabbix_agentd.conf mit denselben Server-Zeilen wie oben, plus AllowRoot=1. Der Grund: Die statische glibc kann keine Benutzer aus /etc/passwd auflösen, also kann der Agent nicht zu einem anderen Benutzer wechseln. Dazu ein procd-Init-Script:

#!/bin/sh /etc/rc.common
START=95
USE_PROCD=1
start_service() {
    procd_open_instance
    procd_set_param command /usr/sbin/zabbix_agentd -c /etc/zabbix/zabbix_agentd.conf -f
    procd_set_param respawn
    procd_close_instance
}

Die Dateien in /etc/sysupgrade.conf eintragen, damit sie ein Firmware-Update überleben. Das Template ist dann „Linux by Zabbix agent active“, und bis auf zwei Items (Paketliste, Benutzeranzahl) funktioniert alles.

Fehlersuche

Die drei Befehle, mit denen ich jedes Agent-Problem gefunden habe:

sudo tail -n 20 /var/log/zabbix/zabbix_agent2.log
sudo zabbix_agent2 -t agent.hostname
sudo grep -i "not found|active checks" /var/log/zabbix/zabbix_server.log | tail

Das Agent-Log sagt, ob der Agent den Server erreicht. Das Server-Log sagt, ob der Server den Hostnamen kennt. Zwischen diesen beiden Logs liegt praktisch jeder Fehler.

Weiter geht es

Jetzt haben wir Hosts, die Daten liefern. Im nächsten Teil sorgen wir dafür, dass man es mitbekommt, wenn etwas schiefgeht: Telegram-Benachrichtigungen einrichten.