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

von

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-Config
    In 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