Wazuh Dashboard Fehler „Socket ‚auth‘ cannot receive connections“ in 4.11.2 beheben: API erreichbar, aber Manager-Authd/Socket blockiert

von

Einleitung

Wenn das Wazuh Dashboard zwar lädt, aber bei API-Aufrufen mit [WazuhError]: API error: ERR_BAD_RESPONSE - Error connecting with socket: Socket 'auth' cannot receive connections abbricht, ist die Lage oft trügerisch: Der Wazuh API-Port (55000) kann erreichbar sein, während intern eine Manager-Komponente nicht verfügbar ist. Gerade bei Single-Node-Installationen führt das schnell zu einer Situation, in der Agents zwar existieren, aber Status/Enrollment/Ansichten im Dashboard unzuverlässig sind. Dieser Beitrag erklärt, was dieser Socket-Fehler technisch bedeutet, warum „API ist erreichbar“ nicht ausreicht, und wie man die Ursache sauber und nachhaltig behebt.

Ausgangslage / Problemstellung

  • Wazuh Version: 4.11.2, Single Node
  • Dashboard zeigt Fehler:
    Error connecting with socket: Socket 'auth' cannot receive connections
  • Der API-Endpunkt antwortet per curl -k https://<wazuh-ip>:55000 korrekt mit Unauthorized (also: Port offen, API-Prozess antwortet).
  • Nach Ergänzung einer <auth>– und <remote>-Konfiguration im Manager und anschließendem Neustart funktioniert das Dashboard wieder (Agents sichtbar).
  • Danach fällt auf: Ein vorheriger Cluster-Bezug („node01“) ist im Dashboard plötzlich „undefined cluster“.

Technische Analyse

1) Was der Fehler wirklich bedeutet

Die Wazuh API ist ein eigener Dienst, der intern über lokale Mechanismen (Sockets/IPC) mit Manager-Komponenten spricht. Der Socket-Fehler „Socket ‚auth‘ cannot receive connections“ bedeutet typischerweise:

  • Die API kann eine intern benötigte Manager-Komponente (häufig Auth/Enrollment) nicht erreichen, oder
  • die Komponente läuft nicht, ist falsch konfiguriert oder kann ihren Socket nicht öffnen.

Wichtig: Dass curl auf Port 55000 eine JSON-Antwort liefert, beweist nur, dass die API als Webdienst erreichbar ist – nicht, dass alle internen Manager-Subsysteme funktionieren.

2) Warum das plötzlich nach Konfigurationsänderungen passiert

In Single-Node-Setups ist eine häufige Ursache, dass die Authd-/Enrollment-Konfiguration im Manager entweder:

  • deaktiviert ist,
  • fehlerhaft ist (z. B. falsche Pfade zu Zertifikaten/Keys),
  • oder der Manager nach einer Änderung nicht sauber gestartet ist und einzelne Subservices nicht hochkommen.

In deinem Fall war der „Fix“ ein <auth>-Block, der den Enrollment-/Auth-Service explizit aktiviert. Das passt sehr gut zum beobachteten Verhalten: Dashboard/API-Funktionen, die intern den Auth-Socket nutzen (direkt oder indirekt), werden wieder stabil, sobald der Manager inkl. Auth-Komponente korrekt läuft.

3) Warum „undefined cluster“ im Dashboard auftaucht

Das Feld „Cluster“ im Dashboard ist Metadaten-abhängig. Wenn Clustering nicht aktiv ist oder Cluster-Attribute fehlen/uneinheitlich sind, kann das Dashboard Agents als „undefined“ anzeigen. In Single-Node-Installationen ist das nicht zwingend kritisch – es ist oft nur ein Hinweis darauf, dass:

  • Clustering gar nicht konfiguriert ist (normal bei Single Node), oder
  • durch Konfig-Edits ein vorher vorhandener Cluster-Kontext/Name nicht mehr konsistent ermittelt wird.

Kurz: Die Auth-Konfiguration kann dein Dashboard-Problem beheben, hat aber mit Cluster-Metadaten nur indirekt zu tun – „undefined cluster“ ist häufig ein separater Hygiene-Punkt.

Lösung / Best Practices

1) Manager/API-Dienste auf einen sauberen Zustand bringen

Auf Single Node sollten mindestens diese Checks Standard sein:

  • systemctl status wazuh-manager (muss „active (running)“ sein)
  • systemctl status wazuh-api (je nach Packaging/Setup)
  • Manager-Logs auf Startfehler prüfen (Zertifikats-/Socket-/Permission-Fehler)

Ein einfacher Neustart kann Symptome beheben, ersetzt aber nicht die Ursachenanalyse. Wenn der Fehler wiederkommt, liegt meist eine Konfig- oder TLS-Datei-Problematik vor.

2) Auth/Enrollment-Konfiguration minimal, korrekt und nachvollziehbar halten

Wenn du Agent Enrollment (Authd) brauchst, ist ein sauberer <auth>-Block sinnvoll. Achte dabei besonders auf:

  • <disabled>no</disabled> (sonst ist der Dienst aus)
  • korrekte Zertifikat-/Key-Pfade (existieren, Rechte passen, PEM-Format korrekt)
  • keine unnötig permissiven Einstellungen in Produktion (z. B. allowed-ips any, ssl_verify_host no) – das ist funktional, aber sicherheitlich riskant.

Wenn Enrollment nicht benötigt wird, sollte man vermeiden, „zufällig“ Security-relevante Auth-Services mit lockeren Defaults zu aktivieren, nur um ein UI-Problem zu kaschieren. Besser: gezielt prüfen, welche Komponente den Socket-Fehler auslöst und diese korrekt konfigurieren.

3) API-Tests richtig durchführen (Token, nicht „leere Felder“)

Ein Unauthorized auf / ist erwartbar ohne Token. Der korrekte Test ist:

  • Token holen über /security/user/authenticate?raw=true
  • dann API-Endpunkte mit Authorization: Bearer <token> abfragen

Wenn du mit Token zwar eine Antwort bekommst, aber Felder wie api_version/hostname leer bleiben, ist das ein Warnsignal: Die API erreicht zwar ihren Web-Stack, bekommt aber intern nicht alle Informationen sauber aus dem Manager.

4) „undefined cluster“ sauber einordnen und korrigieren

Bei Single Node ist es legitim, dass kein Cluster-Name existiert. Wenn du aber erwartest, dass „node01“ angezeigt wird, dann war faktisch vorher irgendwo ein Cluster-Kontext konfiguriert/übernommen. Best Practices:

  • Entscheide bewusst: Single Node ohne Cluster (dann „undefined“ tolerieren) oder Cluster sauber aktivieren (dann Cluster-Name/Node-Name konsistent konfigurieren).
  • Vermeide Mischzustände (teilweise Cluster-Parameter, teilweise nicht), weil sie UI-Metadaten und interne Module irritieren können.

5) Sicherheitshinweis zu den geposteten Settings

Konfigurationen wie:

  • <allowed-ips>any</allowed-ips>
  • <ssl_verify_host>no</ssl_verify_host>
  • Enrollment „remote_enrollment yes“ ohne restriktive Quellen

sollten in produktiven Umgebungen durch restriktive Policies ersetzt werden (IP-Scopes, Host Verification, saubere PKI). Sonst wird der Enrollment-Kanal unnötig angreifbar (Missbrauch für unerwünschte Registrierungen/Key-Issuing).

Lessons Learned / Best Practices

  • API-Port erreichbar ≠ Wazuh intern gesund: Socket-Fehler deuten fast immer auf eine nicht erreichbare Manager-Komponente hin.
  • Nach Config-Edits immer Dienstzustand validieren: Nicht nur „restart“, sondern Logs/Status prüfen, ob Subdienste tatsächlich laufen.
  • Diskrete Ursache statt „Konfig reinwerfen“: Ein funktionierender <auth>-Block kann Symptome beheben, sollte aber bewusst und sicher betrieben werden.
  • Cluster-Anzeige im Dashboard ist Metadaten-getrieben: Single Node kann „undefined“ sein; wer Cluster-Namen erwartet, muss Cluster konsistent konfigurieren.
  • Sichere Defaults setzen: Enrollment/Remote-Zugriff niemals dauerhaft „any/no verify“ lassen, wenn es nicht zwingend erforderlich ist.

Fazit

Der Fehler „Socket ‚auth‘ cannot receive connections“ ist ein klassischer Fall von „API lebt, aber intern fehlt ein Dienst“. In Wazuh 4.11.2 ist die häufigste Ursache ein nicht laufender oder fehlerhaft konfigurierter Auth/Enrollment-Baustein im Manager. Ein sauber aktivierter und korrekt abgesicherter <auth>-Block plus ein sauberer Manager-Neustart bringt die interne Socket-Kommunikation wieder in Ordnung. Die Nebenbeobachtung „undefined cluster“ ist meist eine getrennte Metadaten-/Konfigurationsfrage und sollte bewusst als Single-Node-Standard akzeptiert oder durch konsistente Cluster-Konfiguration bereinigt werden.

https://wazuh.slack.com/archives/C07CNG3M11N/p1764673862212469