Zabbix Agent 2 – Monitoring (Stack-Template)

Zabbix Agent 2 für Host- und Docker-Monitoring auf dem Server. Liefert Metriken an den zentralen Zabbix-Server und kann über das Traefik-Netz dessen interne Metrics/Ping (http://traefik:8082) mit abfragen. Betrieb im Passive-Mode: der Zabbix-Server fragt den Agent auf Port 10050 ab.

Template-Hinweis: Dieses Repo enthält nur Platzhalter (mein-server, example.com). Vor dem Produktiveinsatz die .env vollständig anpassen.

---

1. Voraussetzungen

• Docker + Docker Compose v2
• Das externe Docker-Netz traefik_proxy_network muss existieren (wird vom Traefik-Stack angelegt): docker network create traefik_proxy_network
• Ein erreichbarer Zabbix-Server, der den Agent auf Port 10050 abfragt
• Der Host muss im Zabbix-Frontend mit exakt dem ZBX_HOSTNAME angelegt sein

---

2. Einrichtung (Schritt für Schritt)

1. .env anpassen:

   • ZBX_HOSTNAME → eindeutiger Name (identisch zum Host im Zabbix-Frontend)
   • ZBX_SERVER_HOST → Adresse/IP des Zabbix-Servers
   • ZABBIX_IMAGE_TAG → zur Major-Version des Servers passend (Default alpine-7.0-latest)

2. Docker-GID ermitteln und in die .env eintragen (für den Socket-Zugriff):

   stat -c '%g' /var/run/docker.sock
   

   → Wert nach DOCKER_GID= setzen.

3. Starten:

   docker compose up -d
   

---

3. Worauf besonders achten

• traefik_proxy_network zuerst anlegen – sonst startet der Stack nicht.
• Port 10050 muss vom Zabbix-Server erreichbar sein (Passive-Mode). Ggf. Firewall öffnen bzw. das Port-Mapping auf das richtige Interface beschränken.
• DOCKER_GID ist host-spezifisch – auf jedem Server neu ermitteln. Falsche GID = Agent kann den Docker-Socket nicht lesen (Docker-Plugin liefert keine Daten).
• Agent-Version ↔ Server-Version: Der Agent sollte nicht neuer als der Server sein. Im Zweifel die gleiche LTS-Linie verwenden.
• Socket read-only: Der Agent liest nur Status – :ro genügt (im Gegensatz zu Autoheal, das neu startet und :rw braucht).

---

4. Was wird überwacht?

Bereich	Wie
Docker-Container	Docker-Plugin via Socket (configs/zabbix-agent2/plugins.d/docker.conf)
Host-System	eingebaute Agent2-Items (CPU, RAM, Disk, …)
Traefik (optional)	HTTP-Checks gegen http://traefik:8082/metrics bzw. /ping

Der Traefik-Endpoint ist nur netzintern erreichbar – deshalb hängt der Agent im traefik_proxy_network.

---

5. Konfiguration

Die Agent-Konfiguration läuft über Umgebungsvariablen (.env → Compose), nicht über eine eigene zabbix_agent2.conf. Das offizielle Image generiert die Konfiguration daraus.

Variable (.env)	Beschreibung
ZABBIX_IMAGE_TAG	Image-Version (LTS-Linie)
ZBX_HOSTNAME	Hostname im Zabbix-Frontend
ZBX_SERVER_HOST	Zabbix-Server (→ ZBX_PASSIVESERVERS)
ZBX_PASSIVE_ALLOW	Passive Checks erlauben (true)
ZBX_ACTIVE_ALLOW	Active Checks (false)
DOCKER_GID	GID der Docker-Gruppe des Hosts (für Socket-Zugriff)
PROXY_NETWORK	Name des externen Traefik-Netzes
RESTART	Restart-Policy

Plugin-Konfiguration liegt unter configs/zabbix-agent2/plugins.d/.

---

6. Nützliche Befehle

docker compose config -q          # Konfiguration validieren (.env-Auflösung prüfen)
docker compose up -d              # Starten
docker compose logs -f            # Logs verfolgen
docker compose down               # Stoppen

# Verbindung vom Server testen (vom Zabbix-Server aus):
zabbix_get -s <host-ip> -k agent.ping

# Erreichbarkeit des Traefik-Endpoints aus dem Agent-Container:
docker exec <container> wget -qO- http://traefik:8082/ping

---

7. Troubleshooting

Docker-Plugin liefert keine Daten:

• DOCKER_GID prüfen (stat -c '%g' /var/run/docker.sock) – muss zur Host-GID passen
• Socket-Mount vorhanden? (/var/run/docker.sock)

Zabbix-Server erreicht den Agent nicht:

• Port 10050 offen / erreichbar?
• ZBX_SERVER_HOST korrekt (landet in ZBX_PASSIVESERVERS)?
• Host im Frontend exakt mit ZBX_HOSTNAME benannt?

Stack startet nicht:

• Externes Netz vorhanden? docker network ls | grep traefik_proxy_network

---

8. CI/CD & Spiegelung

Die Pipeline (.forgejo/workflows/ci.yml) läuft self-hosted auf Forgejo, ganz ohne externe Actions (Checkout per git clone):

• validate (jeder Push/PR auf main + Tags): docker compose config -q, yamllint (relaxed) und gitleaks (nur Working-Tree). Es wird docker compose v2 genutzt (Runner-Image catthehacker/ubuntu:act-latest; nötig u. a. für v2-Keys wie dockerfile_inline), apt nur als Fallback – kein 64-MB-github-Download.
• mirror (nur Push, needs: validate): spiegelt main + Tags erst nach grünen Checks nach Codeberg (Org Docker-Stacks), mit Retry gegen transiente 502/504. Forgejos eingebauten Push-Mirror dafür nicht zusätzlich aktivieren.
• release (nur Tag v*): baut ein schlankes Deploy-ZIP und hängt es an ein Forgejo-Release und – als Backup – an ein Codeberg-Release (die Releases-Unit am Codeberg-Repo wird dabei automatisch aktiviert).

Release auslösen:

git tag v1.1
git push origin v1.1

Details siehe CICD-Actions.md.

Lizenz

Copyright (C) 2026 Christian Säum – web-seo-consulting.eu

Dieses Projekt steht unter der GNU Affero General Public License, Version 3 oder (nach deiner Wahl) einer späteren Version (AGPL-3.0-or-later). Der vollständige Lizenztext steht in der Datei LICENSE.

Du darfst die Software nutzen, weitergeben und – auch kommerziell – verkaufen. Gibst du eine veränderte Fassung weiter oder betreibst du sie über ein Netzwerk (z. B. als Dienst), muss deren vollständiger Quellcode ebenfalls unter der AGPL-3.0-or-later verfügbar sein. Der Copyright-Hinweis und die Nennung des ursprünglichen Autors dürfen nicht entfernt werden.

Diese Angabe betrifft nur die in diesem Repository enthaltenen eigenen Dateien (Konfiguration, Skripte, Anpassungen). Eingebundene Fremdsoftware und Container-Images unterliegen weiterhin ihren eigenen Lizenzen.