Agent-Failover im Wazuh-Cluster: Zentral verwalten oder doch individuelle Konfiguration?

Einleitung

Bei verteilten Wazuh-Installationen mit hoher Agentenzahl ist eine zentrale, ausfallsichere Konnektivität zwischen Agents und Servern entscheidend. Besonders in bestehenden Umgebungen mit 100+ Agents stellt sich die Frage, wie man Agent-Failover so umsetzt, dass sowohl Stabilität als auch Wartbarkeit gewährleistet sind.

In diesem Artikel analysieren wir typische Ansätze, zeigen die Grenzen der nativen Wazuh-Mechanismen auf und geben Best-Practices für produktive Wazuh-Cluster mit Agent-Failover.

Ausgangslage / Problemstellung

Ein Administrator betreibt eine All-in-One-Umgebung, die inzwischen zu einem verteilten Wazuh-Cluster mit zwei Indexern und zwei Server-Worker-Knoten skaliert wurde. Insgesamt sind rund 150 Agents im Einsatz. Die Forderung ist ein Agent-Failover, also automatische Umschaltung der Agents auf andere Manager-Nodes, wenn der primäre Manager ausfällt.

Die zentrale Frage lautet:

Muss die Failover-Konfiguration manuell auf allen 150 Agents geändert werden oder gibt es einen zentralisierten oder automatisierten Weg?

Technische Analyse

Wie Wazuh Agent-Failover funktioniert

Wazuh unterstützt zwei grundlegende Arten, Agents an mehrere Manager anzubinden:

1. Direktes Failover über mehrere <server>-Einträge im Agent-ConfigIn der <client>-Sektion der Datei /var/ossec/etc/ossec.conf können mehrere <server>-Abschnitte mit Adresse/Port der verschiedenen Manager angegeben werden. In diesem Failover-Modus versucht der Agent der Reihe nach, eine Verbindung zu allen gelisteten Manager-Knoten aufzubauen, bis ein erreichbarer gefunden ist. Beispiel: <client> <server> <address>10.0.0.101</address> </server> <server> <address>10.0.0.102</address> </server> <server> <address>10.0.0.103</address> </server> </client> Ohne Load Balancer wäre dies der einzige nativen Agent-Failover-Mechanismus von Wazuh.
2. Zentraler Load Balancer vor den Manager-Nodes Wazuh empfiehlt, einen Load Balancer als zentralen Endpunkt für alle Agents zu verwenden. Der Load Balancer verteilt Agent-Verbindungen auf die verfügbaren Serverknoten und übernimmt die Erkennung ausgefallener Manager-Nodes. Dadurch wird der Failover-Mechanismus des Netzwerks genutzt, ohne dass Agents mehrere Manager-IPs kennen müssen. Beliebte Load Balancer sind NGINX oder HAProxy, welche TCP-Traffic (z. B. Port 1514) zwischen Agents und Manager-Nodes verteilen.

Welche zentralisierten Konfigurationsmöglichkeiten gibt es?

Wazuh verfügt über eine zentrale Konfigurationsverteilung über agent.conf, die vom Manager an Agents verteilt wird (§ zentralisierte Konfigurationsmechanismen). Allerdings deckt diese nicht die <client><server>-Adressierung ab – diese muss lokal im Agent-ossec.conf gesetzt werden.

Das bedeutet:

• Standardmäßig gibt es keine native Wazuh-Funktion, um agentenseitig die Failover-Serverliste automatisch über den Manager zu verteilen.
• Die Fähigkeit, Konfigurationen zentral zu verteilen, umfasst viele Module, aber nicht die Netzwerk-Manager-Defintion in <client>, die essenziell für den Failover-Modus ist.

DNS oder VIP als alternative „Tricklösung“

Ein Ansatz aus der Community ist, einen DNS-Alias oder virtuellen IP-Eintrag (VIP) einzusetzen, der alle Manager-IPs abdeckt. Die Agents verbinden sich dann zu einem FQDN, hinter dem mehrere A-Records oder ein VIP liegt. Fällt ein Knoten aus, sorgt DNS oder das VIP-Failover für Umschaltung. Dies simuliert ein Agent-Failover ohne Mehrfach-IP-Einträge für alle Agents.

Lösung / Best Practices

1. Empfehlung: Load Balancer einführen

Warum Ein Load Balancer zwischen Agents und Wazuh-Servern bietet folgende Vorteile:

• Zentrale Management-Adresse für Agents, die nicht bei jedem Server-Add/Remove angepasst werden muss.
• Automatisches Failover und Lastverteilung, auch wenn einzelne Manager ausfallen.
• Skalierbarkeit, da neue Manager-Nodes hinzugefügt werden können, ohne Agents neu konfigurieren zu müssen.

Wie

1. Setze einen TCP-Load-Balancer (z. B. NGINX, HAProxy) vor die Wazuh-Manager-Nodes.
2. Konfiguriere ihn als zentralen Endpunkt auf Port 1514.
3. Passe die Agent-ossec.conf an, damit Agents nur noch diesen Load-Balancer-Endpunkt verwenden. (Einmalig, nicht pro Manager).

Beispiel (NGINX stream):

stream {
  upstream wazuh_cluster {
    server 10.0.0.101:1514;
    server 10.0.0.102:1514;
  }
  server {
    listen 1514;
    proxy_pass wazuh_cluster;
  }
}

2. Alternativ: Direkte Mehrfach-Manager-Einträge

Ohne Load Balancer bleibt die einzige native Methode:

• Mehrere <server>-Einträge in der ossec.conf auf jedem Agent.

Nachteil: Das muss auf allen Agenten manuell oder via Konfigurationsmanagement automatisiert werden (z. B. Ansible, Puppet, Chef).

3. DNS/VIP-basierte Lösung

Setze einen DNS-Eintrag oder VIP, der mehrere Manager-IPs abdeckt.

• Agenten referenzieren nur ein DNS-Name.
• DNS-Round-Robin oder VIP-Failover übernimmt Lastverteilung bzw. Failover.

Nachteil: DNS-Cache und TTL-Probleme können verzögerte Umschaltung bewirken.

Lessons Learned / Best Practices

• Zentrale Konfiguration ist stark, deckt aber nicht Agents’ <server>-Liste ab. Wazuh verteilt über agent.conf viele Einstellungen, aber nicht die Manager-Ziele selbst.
• Automatisierung ist Pflicht bei vielen Agents. Nutze CM-Tools (Ansible etc.), wenn ohne Load Balancer gearbeitet wird.
• Load Balancer erleichtert Failover und Skalierung. Der Agent muss nur einmal konfiguriert werden – der Load Balancer regelt den Rest.
• Beobachte DNS-Lösungen kritisch. Sie funktionieren, sind jedoch von TTL und DNS-Serververhalten abhängig.

Fazit

Ein echtes Agent-Failover über mehrere Server ohne Load Balancer ist zwar mit mehreren <server>-Einträgen in der ossec.conf technisch möglich, aber betriebsaufwendig und muss aktuell auf jedem Agenten einzeln vorgenommen werden – es gibt dafür keine zentrale native Wazuh-Automatik.

Daher lautet die empfohlene Lösung für eine produktive Umgebung mit vielen Agents:

1. Einen Load Balancer einführen und
2. Agents zentral über diesen Load Balancer verbinden lassen, statt viele Manager-IPs auf jedem Agenten zu pflegen.

Damit erreicht man Ausfallsicherheit, Lastverteilung und eine wartbare Betriebsstruktur.

https://wazuh.slack.com/archives/C07CCCCGHHP/p1767868822257249

Quelle

Dieser Artikel stammt aus dem Wazuh-Blog von m.a.x. it (veröffentlicht am 7. Februar 2026).

Unterstützung von m.a.x. it

Bei Einführung, Betrieb und Feintuning von Wazuh (SIEM) unterstützt Sie m.a.x. it mit SIEM-Services auf Open-Source-Basis.

Über m.a.x. it Die m.a.x. Informationstechnologie AG ist seit über 30 Jahren IT-Partner mittelständischer und großer Unternehmen in München und bietet maßgeschneiderte Lösungen und Services in den Bereichen Cloud, Cybersecurity, Netzwerk, Windows, Linux und Softwareentwicklung. Sie haben eine Frage zu diesem Artikel oder brauchen Unterstützung? Kontakt aufnehmen