„Duplicate agent name“ bei der Wazuh-Agent-Enrollment: Ursachen in Agent-Inventory, Load Balancer und Authd-Debugging

von

Einleitung

Die Wazuh-Agent-Enrollment ist der erste kritische Schritt, bevor Telemetrie, FIM, Vulnerability Detection oder Active Response überhaupt zuverlässig funktionieren. Wenn der Manager die Registrierung mit Duplicate agent name ablehnt, ist das selten nur ein „Name-Problem“. In der Praxis steckt häufig ein Zustand dahinter, in dem Agenten wiederholt (und erfolglos) re-enrollen, der Manager alte Agent-Identitäten nicht sauber loswird oder ein Load Balancer Enrollment- und Datenkanal so beeinflusst, dass der Enrollment-Handshake nie sauber abgeschlossen wird. Das Ergebnis: immer neue Agent-IDs mit Never connected, wachsende Agentenlisten und fehlende Sichtbarkeit im SIEM.

Ausgangslage / Problemstellung

Symptome (aus Logs und CLI-Ausgaben):

  • Agent-Log meldet wiederholt:
    • ERROR: Duplicate agent name: alpha-mongodb1. Unable to add agent (from manager)
    • anschließend „Waiting for server reply“ und wiederholte Reconnects.
  • Netzwerkpfade scheinen grundsätzlich offen (Telnet auf 1514/1515 verbindet kurz), dennoch keine stabile Enrollment.
  • Auf dem Manager zeigt agent_control -l viele Agenten als Disconnected und mehrere neue Einträge mit Varianten desselben Namens (alpha-mongodb1, Alpha-mongodb1, alpha-mongodb-01) mit Status Never connected.
  • Setup ist nicht „single manager“: Es existieren Manager/Worker, Dashboard, zwei Indexer sowie ein Load Balancer vor der Agent-Kommunikation.

Relevanz:
Dieser Zustand führt nicht nur zu Enrollment-Fehlern, sondern typischerweise auch zu Datenlücken: Wenn die Agent-Identität nicht stabil wird (Key-Austausch, Zuordnung zu einer Agent-ID, persistente Verbindung), bleibt der Endpoint operativ „blind“ für Detection und Compliance.

Technische Analyse

1) „Duplicate agent name“ ist oft ein Inventar-/Lifecycle-Problem, nicht nur ein Tippfehler

Wazuh erzwingt eindeutige Agent-Namen. Wenn ein Agent sich mit einem Namen registrieren möchte, der im Manager bereits existiert, wird die Enrollment abgelehnt. Das ist erwartetes Verhalten. In vielen Umgebungen wird der Agent-Name zudem automatisch aus dem Hostnamen abgeleitet, wenn kein expliziter Name gesetzt ist – doppelte Hostnamen oder wiederverwendete Namen nach Neuinstallation führen dann zu Kollisionen.

Was die Situation „ungewöhnlich“ macht: Selbst nach dem Entfernen taucht derselbe Name wieder auf – aber mit neuer ID und Never connected. Das deutet darauf hin, dass die Enrollment nicht sauber bis zum stabilen „Connected“-Zustand durchläuft und der Agent wiederholt neue Enrollment-Versuche startet, während auf der Manager-Seite bereits (unvollständige) Agent-Objekte existieren.

2) Viele „Disconnected“ + „Never connected“ Agenten sind ein starkes Signal für Connectivity- oder LB-Probleme

Wenn nahezu alle Agenten Disconnected sind, ist das in der Regel kein isoliertes Namensproblem. Häufige Ursachen in Multi-Manager-Setups sind:

  • Enrollment-Port (1515/TCP) wird über den Load Balancer auf wechselnde Backends verteilt, obwohl Enrollment/Key-Handling konsistent über die zuständige Instanz erfolgen sollte.
  • Datenkanal (1514/TCP) wird ohne Session-Stickiness oder mit aggressiven Timeouts/Resets betrieben, sodass TLS/Key-Verhandlung oder der dauerhafte TCP-Stream instabil ist.
  • NAT/LB verändert Quell-IP/Session-Charakteristiken so, dass Manager-Sicht und Agent-Sicht auseinanderlaufen (z. B. „IP: any“ maskiert zwar IP-Bindungen, löst aber keine instabilen Sessions).

Wazuh dokumentiert die Rollen der Ports klar: 1514/TCP für Agent-Kommunikation und 1515/TCP für Enrollment per automatischer Agent-Request.
Das heißt: Offen ist nicht gleich stabil – ein Telnet-Connect, der sofort wieder vom Server geschlossen wird, beweist nur, dass ein Listener erreichbar ist, nicht dass das Enrollment-Protokoll erfolgreich ist.

3) „Gelöscht, aber kommt wieder“: Warum sich Agenten in Schleifen neu registrieren

Ein häufiger Loop entsteht, wenn:

  • der Agent seine lokale Identität/Keys verliert (Neuinstallation, Verzeichnis gelöscht),
  • der Manager noch einen gleichnamigen Agenten kennt,
  • gleichzeitig aber die Netzwerk-/LB-Situation verhindert, dass der „richtige“ Agent-Eintrag je in einen stabilen verbundenen Zustand wechselt.

Dann erzeugt jeder neue Versuch entweder wieder eine Ablehnung (weil Name belegt) oder – je nach Deployment-Parametern – neue Agent-IDs, die nie online gehen. In Community-Fällen wird zudem darauf hingewiesen, dass „Force“-Enrollment zwar Duplikate überschreiben kann, aber bei instabiler Connectivity auch eine Re-Enrollment-Schleife verschärfen kann.

Lösung / Best Practices

Die zuverlässigste Vorgehensweise ist ein dreiteiliger Fix: (A) Inventory bereinigen, (B) Agent-seitig Identität stabilisieren, (C) Enrollment- und Datenpfad am Load Balancer korrekt trennen bzw. stabilisieren.

A) Manager-Inventar konsequent bereinigen (Disconnected/Never connected entfernen)

  1. Alle verwaisten Agenten entfernen
    • Entferne insbesondere Einträge mit Never connected sowie alte Disconnected-Agenten, die nicht mehr existieren.
    • In großen Umgebungen ist das über Dashboard „Agents management > Summary“ praktikabel (bulk remove), alternativ über CLI (manage_agents -r) oder API (für Automatisierung).
  2. Nicht nur „einen“ Agent löschen – Varianten bereinigen
    • Da alpha-mongodb1 und Alpha-mongodb1 als unterschiedliche Namen auftauchen, muss die Bereinigung case-sensitiv vollständig erfolgen (auch Tippfehler-Varianten wie alpha-mongodb-01).
  3. Cluster-Kontext prüfen (Manager/Worker)
    • In verteilten Manager-Setups sicherstellen, dass die Löschung auf der Instanz/Role erfolgt, die Enrollment/Key-Handling tatsächlich ausführt, und dass der Zustand konsistent repliziert wird.

B) Agent-Identität explizit setzen und lokal sauber starten

  1. Agent-Name explizit konfigurieren statt Hostname-Ableitung
    • Lege einen eindeutigen, stabilen Namen fest (z. B. nach CMDB-Asset-ID). So verhinderst du Kollisionen durch gleiche Hostnames.
  2. Alte lokale Agent-Keys/Registrierungsartefakte entfernen (bei Neuinstallation)
    • Gerade nach „installiert → gelöscht → wieder installiert“ bleiben je nach OS Reste zurück (Windows/Linux unterschiedlich). Stelle sicher, dass der Agent wirklich „clean“ ist, bevor du neu enrollst.
  3. Agent-Version ≤ Manager-Version sicherstellen
    • Mismatches führen zwar nicht immer zu Duplicate agent name, aber sehr häufig zu Enrollment- und Handshake-Problemen. Ein stabiler Lifecycle setzt kompatible Versionen voraus.

C) Load Balancer korrekt konfigurieren: Enrollment (1515) und Datenkanal (1514) getrennt denken

  1. Enrollment-Port 1515/TCP möglichst nicht „round-robin“ über mehrere Backends verteilen
    • Enrollment ist ein zustandsbehafteter Prozess (Key-Erzeugung, Registrierung). In Multi-Manager-Architekturen ist es meist robuster, Enrollment gezielt auf die dafür vorgesehene Instanz zu terminieren (oder mindestens mit klarer Stickiness/Session-Konzept).
  2. Datenkanal 1514/TCP braucht langlebige TCP-Sessions
    • Setze angemessene Idle-Timeouts, vermeide Connection-Resets, und stelle sicher, dass der LB keine Protokoll-„Optimierungen“ erzwingt, die langlebige Agent-Verbindungen stören.
  3. Logs des Load Balancers als primäre Fehlerquelle nutzen
    • Wenn nahezu alle Agenten Disconnected sind, ist LB-Telemetrie (Resets, Timeouts, Backend-Flaps) meist der schnellste Weg, den „Loop“ zu belegen.

D) Zielgerichtetes Troubleshooting: authd-Debug aktivieren (upgrade-sicher)

Wenn die Ursache nicht sofort sichtbar ist, hilft Debug-Logging für Enrollment (authd):

  1. Debug korrekt setzen
    • Wazuh weist darauf hin, dass /var/ossec/etc/internal_options.conf bei Upgrades überschrieben werden kann und für dauerhafte Anpassungen eine lokale Override-Datei genutzt werden sollte.
    • Best Practice: Debug temporär aktivieren und danach wieder deaktivieren.
  2. Log-Quellen prüfen
    • Wazuh empfiehlt zur Enrollment-Analyse die Logs auf Manager- und Agent-Seite (Manager: /var/ossec/logs/ossec.log; Agent-Pfade OS-abhängig).
  3. Mit reproduzierbarem Enrollment-Test arbeiten
    • Bereinigung → Enrollment eines einzigen Test-Agents → Logs prüfen → erst dann Massendeploy.

Lessons Learned / Best Practices

  • Agent-Namen sind Identitäten: Hostname-Ableitung ist bequem, aber riskant. Explizite Agent-Namen verhindern Kollisionen und beschleunigen Incident Response.
  • Viele „Disconnected“ sind selten Zufall: Wenn die Mehrheit der Agenten offline ist, zuerst LB/Netzwerk stabilisieren, bevor man Agenten „wegklickt“.
  • „Force“-Enrollment mit Vorsicht: Es kann Duplikate überschreiben, aber bei instabiler Connectivity Re-Enrollment-Loops fördern.
  • Enrollment und Datenkanal getrennt betreiben: 1515/TCP (Enrollment) und 1514/TCP (Daten) haben unterschiedliche Anforderungen; „Port offen“ reicht nicht – Stabilität zählt.
  • Debug upgrade-sicher aktivieren: Interne Optionen sind mächtig, aber Änderungen in internal_options.conf sind nicht upgrade-stabil; nutze lokale Overrides und schalte Debug nach der Analyse wieder ab.

Fazit

Duplicate agent name ist in Wazuh häufig das sichtbare Symptom eines tieferliegenden Enrollment-Lifecycle-Problems: verwaiste Agent-Einträge, wiederholte Neu-Registrierungen und vor allem instabile Connectivity – in diesem Fall stark begünstigt durch ein Load-Balancer-Setup vor Manager/Worker. Wer das nachhaltig lösen will, kombiniert konsequente Inventar-Bereinigung, explizite Agent-Identitäten und eine LB-Konfiguration, die langlebige 1514-Verbindungen stabil hält und Enrollment (1515) kontrolliert terminiert. Mit gezieltem authd-Debugging lässt sich die Ursache anschließend belastbar belegen und dauerhaft abstellen.

Mehr zu Wazuh …
https://wazuh.com/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program

Mehr zum Wazuh Ambassador Program …
https://wazuh.com/ambassadors-program/?utm_source=ambassadors&utm_medium=referral&utm_campaign=ambassadors+program

https://wazuh.slack.com/archives/C07BK5RJM3R/p1770969992116559