Wazuh Dashboard: „No API available to connect“ und ERROR3099 in verteilten Setups sauber beheben

von

Einleitung

In verteilten Wazuh-Deployments (Manager/Cluster, Indexer, Dashboard und Load Balancer auf getrennten Hosts) ist die Verbindung zwischen Wazuh Dashboard und Wazuh Server API eine der häufigsten Fehlerquellen. Typische Symptome sind „Wazuh server API seems to be down“, HTTP 401 sowie ERROR3099 - Invalid credentials. Der Effekt ist gravierend: Ohne API-Verbindung kann das Dashboard keine Agenten-, Konfigurations- oder Statusdaten aus dem Manager beziehen – selbst wenn die Weboberfläche grundsätzlich erreichbar ist.

Dieser Artikel zeigt, wie man die Fehler systematisch eingrenzt und in verteilten Umgebungen dauerhaft stabil behebt.

Ausgangslage / Problemstellung

In der beschriebenen Umgebung existieren getrennte Nodes für:

  • 1 Master-Node (Wazuh Manager Master)
  • 1 Worker-Node (Wazuh Manager Worker)
  • 1 Indexer-Node
  • 1 Dashboard-Node
  • 1 Load Balancer

Nach dem Setup ist der Login ins Dashboard zwar möglich, aber die Wazuh-App meldet beim API-Check:

  • Request failed with status code 401
  • ERROR3099 - Invalid credentials
  • ERROR: No API available to connect

Zusätzlich schlägt das Refresh des Index-Patterns fehl, weil keine Indizes wie wazuh-alerts-* gefunden werden. Das ist oft ein Folgeproblem: Wenn die Pipeline Manager → Filebeat → Indexer nicht läuft oder der Indexer leer ist, kann das Dashboard keine Alert-Indizes sehen. Die primäre Blockade in diesem Fall ist jedoch die fehlende/fehlerhafte API-Anmeldung am Manager.

Technische Analyse

In verteilten Installationen hängen die genannten Fehler typischerweise an drei Kernpunkten:

  1. Falscher API-Endpunkt in wazuh.yml (URL/TLS/CN/SAN)
    • Die Dashboard-Integration spricht die Wazuh Server API standardmäßig via https://<manager>:55000 an.
    • Wenn in wazuh.yml ein Hostname/IP genutzt wird, der nicht zum Zertifikat passt (CN/SAN), sind TLS-Fehler vorprogrammiert.
    • In Clustern darf die URL außerdem nicht „irgendein“ Manager sein, sondern muss zuverlässig erreichbar sein (z. B. Master oder ein korrektes VIP/Load-Balancer-Frontend, falls dort die API wirklich sauber durchgereicht wird).
  2. Ungültige oder nicht synchronisierte API-Credentials
    • Das Dashboard authentifiziert sich an der Wazuh Server API mit einem API-User, üblicherweise wazuh-wui. In der Wazuh-Dokumentation ist wazuh-wui explizit als Admin-User für die Kommunikation Dashboard ↔ API beschrieben.
    • In verteilten Umgebungen werden Passwörter häufig mit dem Password-Tool (oder aus Installationsartefakten) ausgelesen/gesetzt – aber anschließend nicht überall nachgezogen. Die Doku weist ausdrücklich darauf hin, dass man in distributed environments Passwörter komponentenübergreifend aktualisieren muss.
  3. Fehlinterpretation „API down“ vs. „Auth schlägt fehl“
    • Der Dashboard-Fehlertext ist irreführend: Ein HTTP 401 oder ERROR3099 bedeutet oft nicht, dass die API down ist, sondern dass der Auth-Flow scheitert.
    • Die Wazuh-Doku empfiehlt deshalb explizit einen CLI-Test vom Dashboard-Node aus, der zuerst ein Bearer-Token holt und danach GET / auf der API absetzt.
    • Erst wenn dieser Test auf Netzwerkebene scheitert (z. B. curl: (7) Failed to connect), ist es tatsächlich ein Reachability-/Port-/Service-Problem.

Lösung / Best Practices

Die folgenden Schritte sind bewusst in einer Reihenfolge aufgebaut, die ohne Rätselraten zum Ziel führt.

1) API-Verbindung vom Dashboard-Node aus „hart“ testen (Token + GET /)

Auf dem Dashboard-Node den von Wazuh dokumentierten Test ausführen (wichtig: <api_url> ist die Wazuh-Manager-IP/Hostname, nicht der Indexer, nicht das Dashboard):

curl -k -X GET "https://<api_url>:55000/?pretty=true" \
  -H "Authorization: Bearer $(curl -u <api_user>:<api_password> -k -X POST 'https://<api_url>:55000/security/user/authenticate?raw=true')"

Interpretation:

  • Kommt ein JSON mit title: "Wazuh API REST" und error: 0, ist die API erreichbar und Auth funktioniert.
  • Kommt 401 / „invalid credentials“ / kein Token → Credentials oder User-Konzept passen nicht.
  • Kommt curl: (7) Failed to connect ... 55000 → Netzwerk/Firewall/Service.

Hinweis: Für Agent Enrollment sind u. a. 1514/TCP, 1515/TCP und 55000/TCP relevant; 55000 ist die API.

2) wazuh.yml auf dem Dashboard korrigieren (URL + User + run_as)

Auf dem Dashboard-Node liegt die relevante Konfiguration unter:

/usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml

Minimal sollte der Block so aussehen (angepasst auf eure Umgebung):

hosts:
  - default:
      url: https://<WAZUH_MANAGER_IP_ODER_FQDN>
      port: 55000
      username: wazuh-wui
      password: "<PASSWORT_VON_wazuh-wui>"
      run_as: true

Wichtige Punkte:

  • url muss zu eurem Zertifikat passen (CN/SAN). Wenn ihr Zertifikate für FQDN ausgestellt habt, nutzt den FQDN – nicht die nackte IP.
  • Nutzt username (nicht user). Das ist seit Wazuh 4.0 relevant und wird in der Dashboard-Troubleshooting-Doku explizit erwähnt.
  • In vielen RBAC-Setups ist run_as: true der erwartete Modus für wazuh-wui. Wenn run_as und Rollenmodell nicht zusammenpassen, führt das in der Praxis häufig zu 401/3099-Symptomen.

Anschließend Dashboard neu starten:

sudo systemctl restart wazuh-dashboard

3) Sicherstellen, dass ihr wirklich das API-Passwort von wazuh-wui verwendet

In der Wazuh-Dokumentation sind die zwei Default-API-User klar benannt:

  • wazuh (API-Admin)
  • wazuh-wui (Admin-User für Dashboard ↔ API-Kommunikation)

In verteilten Installationen ist der häufigste Fehler, dass ein Passwort zwar „vorliegt“, aber:

  • aus dem falschen Artefakt stammt (z. B. alte Datei, falscher Node),
  • bereits geändert wurde,
  • oder nach einer Änderung nicht in wazuh.yml nachgezogen wurde.

Best Practice: Einmal „Single Source of Truth“ definieren (z. B. Secret-Store, Vault, Ansible vars) und von dort konsistent ausrollen.

4) API-Passwörter mit dem offiziellen Password-Tool korrekt ändern (auch wenn „invalid credentials“ blockiert)

Wenn die API-Auth scheitert und ihr Passwörter neu setzen müsst, nutzt das Wazuh Password-Tool gemäß Doku. Wazuh beschreibt explizit, dass man damit sowohl Indexer-Internal-Users als auch Wazuh Server API-User ändern kann.

Relevant für API-User ist der Modus --api/-A, der Admin-User/Passwort benötigt. Beispiel aus der Doku (sinngemäß):

# Auf einem Wazuh-Server (Manager) ausführen:
curl -sO https://packages.wazuh.com/4.14/wazuh-passwords-tool.sh
bash wazuh-passwords-tool.sh --api -u wazuh-wui -p '<NEUES_PASSWORT>' \
  --admin-user wazuh \
  --admin-password '<PASSWORT_DES_API_ADMIN_USERS_wazuh>'

Danach unbedingt:

  • das neue wazuh-wui Passwort in wazuh.yml auf dem Dashboard nachziehen,
  • Dashboard neu starten,
  • CLI-Test (Schritt 1) wiederholen.

Hintergrund: Die Doku betont, dass in distributed environments Passwörter ggf. manuell auf den jeweils betroffenen Komponenten aktualisiert werden müssen.

5) API-Logs zur Ursachenanalyse heranziehen

Wenn es trotz korrekter Credentials weiter scheitert, ist der nächste Schritt immer das API-Log auf dem Manager:

sudo tail -n 200 /var/ossec/logs/api.log

Achtet auf:

  • abweichende Auth-User
  • Token-Fehler
  • Zeit-/Clock-Skew (JWT/Token-Validierung kann bei massiven Zeitabweichungen brechen)
  • Client-IP, von der aus Requests kommen (besonders relevant bei Load Balancern/NAT)

6) Load Balancer: API-Traffic sauber designen (oder bewusst vermeiden)

Viele Setups haben einen Load Balancer „für alles“. Das funktioniert für den Dashboard-Webzugriff meist gut, kann aber bei der API problematisch werden, wenn:

  • TLS am LB terminiert wird, aber Backend-Zertifikate/CNs nicht passen,
  • der LB die Client-IP maskiert und Security/Rate-Limits greifen,
  • nicht klar ist, welcher Manager-Node die API-Anfragen bedienen soll.

Robuste Variante (Best Practice):

  • Dashboard spricht direkt den Master-Manager oder ein dediziertes VIP an, das die API unverändert weiterreicht (TCP-Passthrough), inklusive korrekter Zertifikatskette.
  • Wenn ihr HTTP-Proxying macht, stellt sicher, dass https://<api_url>:55000 wirklich am Backend ankommt und keine Header-/TLS-Inkompatibilitäten entstehen.

Lessons Learned / Best Practices

  • API-Verifikation immer per CLI: Der dokumentierte Token-+GET-Test vom Dashboard-Node trennt Auth-Probleme sauber von Netzwerkproblemen.
  • Verteilte Installationen brauchen Passwort-„Sync-Disziplin“: Passwortänderung ist kein lokales Event – sie muss auf Dashboard/Indexer/Filebeat/Manager konsistent ausgerollt werden (je nach betroffenem User).
  • Zertifikate und Naming sauber planen: Entscheidet euch früh für FQDNs oder IPs und stellt sicher, dass CN/SAN dazu passen – sonst jagt ihr Phantomfehlern hinterher.
  • RBAC-/run_as bewusst konfigurieren: wazuh-wui ist für Dashboard↔API vorgesehen; run_as und Rollenmodell müssen dazu passen, sonst enden selbst korrekte Passwörter in 401/3099.
  • API-Logs sind Pflichtlektüre: Wenn UI-Fehlertexte unklar sind, liefert /var/ossec/logs/api.log die belastbare Wahrheit.

Fazit

ERROR3099 - Invalid credentials und „No API available to connect“ sind in Multi-Node-Wazuh-Setups fast immer auf inkonsistente API-Credentials, eine unpassende wazuh.yml-Konfiguration (URL/TLS/User) oder LB-bedingte Nebenwirkungen zurückzuführen. Wer konsequent mit dem dokumentierten CLI-Token-Test beginnt, danach wazuh.yml korrekt auf wazuh-wui ausrichtet und Passwortänderungen sauber über alle Komponenten synchronisiert, bekommt die Dashboard↔API-Kopplung schnell und dauerhaft stabil.

Quellenverweise (Copy & Paste)

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/C0A933R8E/p1770036965271109