Wazuh 4.14.1: Snapshot-Restore im Dashboard scheitert durch Global State und Security-Indizes

Einleitung

Snapshots sind ein zentraler Bestandteil einer belastbaren Backup-, Recovery- und Migrationsstrategie für den Wazuh Indexer. Sie ermöglichen es, Alert-Indizes, Archivdaten und weitere im Indexer gespeicherte Informationen nach einem Ausfall wiederherzustellen oder in einen neuen Cluster zu übertragen.

Bei der Wiederherstellung eines Snapshots kann jedoch eine Besonderheit des OpenSearch Security Plugins zu Problemen führen: Enthält der Restore-Vorgang den globalen Clusterzustand oder den internen Security-Index, wird die Wiederherstellung aus Sicherheitsgründen abgelehnt. Das kann insbesondere dann verwirrend sein, wenn der Restore über die REST-API funktioniert, derselbe Vorgang über die grafische Oberfläche des Wazuh Dashboards jedoch fehlschlägt.

In einer Wazuh-4.14.1-Umgebung lag die Ursache genau in dieser Abweichung zwischen dem über die Kommandozeile gesendeten Restore-Request und den im Dashboard ausgewählten erweiterten Optionen.

Ausgangslage / Problemstellung

In der betroffenen Umgebung war ein Snapshot bereits erfolgreich in einem registrierten Repository abgelegt worden. Der Benutzer konnte den Snapshot im Wazuh Dashboard anzeigen und den Restore-Dialog öffnen. Die Wiederherstellung über die Benutzeroberfläche schlug jedoch fehl.

Zunächst lag die Vermutung nahe, dass dem verwendeten Dashboard-Benutzer Berechtigungen für Snapshot- und Restore-Operationen fehlten. Bei OpenSearch benötigt ein Benutzer für diese Aufgaben entsprechende Cluster-Berechtigungen, die üblicherweise über die integrierte Rolle manage_snapshots oder eine vergleichbare benutzerdefinierte Rolle bereitgestellt werden. Neben der Rollendefinition muss auch das Role Mapping den Benutzer oder dessen Backend-Rolle korrekt zuordnen.

Ein manueller Restore über die REST-API war mit denselben Zugangsdaten jedoch erfolgreich. Damit war klar, dass die grundlegenden Berechtigungen, die Erreichbarkeit des Indexers und der Zugriff auf das Snapshot-Repository funktionierten.

Der erfolgreiche API-Aufruf verwendete zwei entscheidende Einschränkungen:

{
  "indices": "*,-.opendistro_security,-.plugins_security",
  "include_global_state": false
}

Damit wurden die Security-Indizes aus der Wiederherstellung ausgeschlossen und die Übernahme des globalen Clusterzustands deaktiviert.

Im Dashboard war dagegen eine erweiterte Option zur Wiederherstellung des Clusterzustands aktiviert. Nach dem Deaktivieren dieser Option konnte der Snapshot auch über die Benutzeroberfläche erfolgreich wiederhergestellt werden.

Technische Analyse

Der Wazuh Indexer basiert auf OpenSearch und verwendet dessen Snapshot- und Restore-Funktionen. Ein Snapshot kann dabei mehr enthalten als ausschließlich die Dokumente der ausgewählten Indizes.

Abhängig von der Snapshot-Konfiguration können unter anderem folgende Informationen enthalten sein:

Indexdaten und Shards
Mappings und Indexeinstellungen
Index-Templates
persistente Cluster-Einstellungen
Ingest-Pipelines
Lifecycle-Richtlinien
Alias-Definitionen
globaler Clusterzustand

Der Parameter include_global_state steuert beim Restore, ob der im Snapshot gespeicherte globale Clusterzustand in den Zielcluster übernommen werden soll. Wird er auf false gesetzt, werden die eigentlichen Indizes wiederhergestellt, ohne die globale Konfiguration des Zielclusters durch den Zustand des Quellclusters zu ersetzen.

Warum der Security-Index nicht regulär wiederhergestellt werden sollte

Der Index .opendistro_security enthält die vom OpenSearch Security Plugin verwendete Sicherheitskonfiguration. Dazu können unter anderem folgende Informationen gehören:

interne Benutzer
Rollen
Role Mappings
Action Groups
Mandantenberechtigungen
Authentifizierungs- und Autorisierungsregeln

Eine unkontrollierte Wiederherstellung dieses Indexes könnte die aktive Sicherheitskonfiguration des Zielclusters überschreiben. Im ungünstigsten Fall würden Administratoren ihre Zugriffsrechte verlieren, bestehende Benutzerzuordnungen würden ersetzt oder Sicherheitsrichtlinien eines anderen Clusters würden übernommen.

OpenSearch schränkt die Wiederherstellung deshalb ein: Snapshots, die den globalen Clusterzustand oder den Security-Index enthalten, müssen so wiederhergestellt werden, dass diese Bestandteile ausgeschlossen bleiben. Die OpenSearch-Dokumentation empfiehlt ausdrücklich, .opendistro_security nicht über einen normalen Snapshot-Restore zu übernehmen und include_global_state beim Restore zu deaktivieren.

Der zusätzliche Ausschluss von .plugins_security ist eine defensive Maßnahme für Umgebungen oder Versionen, in denen dieser Name für Security-bezogene Systemdaten verwendet wird. Für eine reine Wiederherstellung von Wazuh-Alert- und Anwendungsindizes werden diese internen Sicherheitsindizes nicht benötigt.

Warum die CLI funktionierte und die Benutzeroberfläche nicht

Der REST-Aufruf enthielt explizit:

"include_global_state": false

Die grafische Oberfläche erzeugt den Restore-Request dagegen anhand der im Restore-Dialog ausgewählten Optionen. Ist dort die Option zur Übernahme des Clusterzustands aktiviert, kann der resultierende Request technisch einem Restore mit aktiviertem Global State entsprechen.

Damit waren die beiden Vorgänge trotz desselben Snapshots und desselben Benutzers nicht identisch:

Restore über REST-API	Restore über Dashboard
Global State ausdrücklich deaktiviert	Clusterzustand in den erweiterten Optionen aktiviert
Security-Indizes ausdrücklich ausgeschlossen	Abhängig von der Indexauswahl möglicherweise enthalten
Wiederherstellung erfolgreich	Wiederherstellung durch Security-Beschränkung abgelehnt

Der erfolgreiche CLI-Test war deshalb ein wichtiger diagnostischer Schritt. Wenn ein Restore mit denselben Zugangsdaten über die API funktioniert, über das Dashboard aber nicht, sollte nicht nur die Rollenbelegung untersucht werden. Zusätzlich muss geprüft werden, welche Parameter die Benutzeroberfläche tatsächlich an die Restore-API übergibt.

Abgrenzung zu einem Berechtigungsproblem

Ein Berechtigungsproblem zeigt typischerweise andere Symptome. Dazu gehören HTTP-Statuscodes wie 401 Unauthorized oder 403 Forbidden sowie Meldungen über fehlende Cluster- oder Indexberechtigungen.

Scheitert der Restore dagegen wegen des globalen Zustands oder eines Security-Indexes, handelt es sich nicht primär um ein Role-Mapping-Problem. Der Request wird in diesem Fall wegen seines Inhalts abgelehnt.

Für die Fehlersuche ergibt sich daraus folgende Einordnung:

Schlägt CLI und UI mit 401 oder 403 fehl, müssen Benutzer, Rollen und Role Mappings geprüft werden.
Funktioniert die CLI mit demselben Benutzer, ist die grundlegende Berechtigung vorhanden.
Funktioniert nur ein eingeschränkter CLI-Request, müssen die Restore-Optionen der UI an diesen Request angeglichen werden.
Enthält die Fehlermeldung Hinweise auf global state, .opendistro_security oder das Security Plugin, müssen diese Bestandteile ausgeschlossen werden.

Lösung / Best Practices

Wiederherstellung über das Wazuh Dashboard

Für die Wiederherstellung über die Benutzeroberfläche sind folgende Schritte sinnvoll:

Im Wazuh Dashboard das Menü öffnen.
Zu Indexer management > Snapshot Management > Snapshots wechseln.
Das gewünschte Snapshot-Repository auswählen beziehungsweise die Snapshot-Liste aktualisieren.
Einen Snapshot mit dem Status Success oder Partial markieren.
Restore auswählen.
Die wiederherzustellenden Datenindizes festlegen.
Interne Security-Indizes nicht in die Wiederherstellung aufnehmen.
Unter Advanced options die Option Include global state beziehungsweise Include cluster state deaktivieren.
Bei einer Wazuh-Indexmigration entsprechend der offiziellen Wazuh-Anleitung sämtliche erweiterten Restore-Optionen deaktiviert lassen.
Den Restore starten und anschließend Clusterzustand und Indizes kontrollieren.

Die aktuelle Wazuh-Dokumentation beschreibt für die Migration von Wazuh-Indizes ebenfalls, dass im Restore-Dialog unter den erweiterten Optionen alle Optionen deaktiviert sein sollen.

Je nach Version der Oberfläche können die Bezeichnungen leicht abweichen. Entscheidend ist, dass der globale beziehungsweise clusterweite Zustand nicht wiederhergestellt wird.

Wiederherstellung über die REST-API

Kann der Restore über die Benutzeroberfläche nicht korrekt eingeschränkt werden, lässt sich der Vorgang direkt über die OpenSearch REST-API ausführen:

curl -k -u '<USER>:<PASSWORD>' \
  -X POST \
  'https://localhost:9200/_snapshot/s3-snapshot/test-snapshot/_restore' \
  -H 'Content-Type: application/json' \
  -d '{
    "indices": "*,-.opendistro_security,-.plugins_security",
    "include_global_state": false
  }'

Dabei müssen folgende Werte angepasst werden:

<USER>: Benutzer mit Snapshot- und Restore-Berechtigungen
<PASSWORD>: Kennwort des Benutzers
localhost: Adresse eines erreichbaren Wazuh-Indexer-Knotens
s3-snapshot: Name des registrierten Snapshot-Repositories
test-snapshot: Name des wiederherzustellenden Snapshots

Wird der Befehl nicht direkt auf dem Indexer ausgeführt, muss localhost durch den Hostnamen oder die IP-Adresse eines Indexer-Knotens ersetzt werden.

Die Option -k deaktiviert die Prüfung des TLS-Zertifikats. Das kann für einen kontrollierten Test hilfreich sein, sollte im produktiven Betrieb jedoch nicht die Standardlösung sein. Besser ist die Angabe der vertrauenswürdigen Certificate Authority:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  -X POST \
  'https://indexer.example.net:9200/_snapshot/s3-snapshot/test-snapshot/_restore' \
  -H 'Content-Type: application/json' \
  -d '{
    "indices": "*,-.opendistro_security,-.plugins_security",
    "include_global_state": false
  }'

Zugangsdaten sollten außerdem nicht dauerhaft im Shell-Verlauf, in Skripten oder in Automatisierungs-Logs gespeichert werden.

Nur benötigte Wazuh-Indizes wiederherstellen

Statt zunächst alle Indizes mit * auszuwählen und anschließend Systemindizes auszuschließen, ist eine Positivliste häufig sicherer.

Beispiel für Wazuh-Alert-Indizes:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  -X POST \
  'https://indexer.example.net:9200/_snapshot/s3-snapshot/test-snapshot/_restore' \
  -H 'Content-Type: application/json' \
  -d '{
    "indices": "wazuh-alerts-*",
    "include_global_state": false,
    "include_aliases": true
  }'

Abhängig von der Umgebung können zusätzlich weitere Indexmuster benötigt werden, beispielsweise Archiv-, Monitoring- oder benutzerdefinierte Indizes. Die vorhandenen Indizes eines Snapshots lassen sich vor dem Restore abfragen:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  'https://indexer.example.net:9200/_snapshot/s3-snapshot/test-snapshot?pretty'

Eine Positivliste reduziert das Risiko, unbeabsichtigt versteckte Systemindizes oder Konfigurationsdaten in den Restore einzubeziehen.

Konflikte mit bereits vorhandenen Indizes vermeiden

OpenSearch kann einen Index nicht unter demselben Namen wiederherstellen, wenn im Zielcluster bereits ein geöffneter Index mit diesem Namen existiert.

Für einen kontrollierten Test empfiehlt sich deshalb eine Umbenennung:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  -X POST \
  'https://indexer.example.net:9200/_snapshot/s3-snapshot/test-snapshot/_restore' \
  -H 'Content-Type: application/json' \
  -d '{
    "indices": "wazuh-alerts-*",
    "include_global_state": false,
    "rename_pattern": "(.+)",
    "rename_replacement": "restored_$1"
  }'

Die wiederhergestellten Indizes erhalten damit beispielsweise den Namen:

restored_wazuh-alerts-4.x-2026.07.25

So können Dokumentanzahl, Mappings und Suchbarkeit geprüft werden, ohne produktive Indizes zu ersetzen. Erst nach erfolgreicher Validierung sollte über das endgültige Umschalten, Reindexing oder Entfernen bestehender Indizes entschieden werden.

Restore-Ergebnis prüfen

Nach dem Start der Wiederherstellung sollte zunächst der Clusterzustand kontrolliert werden:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  'https://indexer.example.net:9200/_cluster/health?pretty'

Anschließend können die wiederhergestellten Indizes angezeigt werden:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  'https://indexer.example.net:9200/_cat/indices?v&s=index'

Für Wazuh-Alert-Indizes ist eine gezielte Abfrage möglich:

curl --cacert /path/to/root-ca.pem \
  -u '<USER>:<PASSWORD>' \
  'https://indexer.example.net:9200/_cat/indices/wazuh-alerts-*?v&s=index'

Neben einem grünen oder zumindest nachvollziehbar gelben Clusterzustand sollten folgende Punkte geprüft werden:

Sind alle erwarteten Indizes vorhanden?
Entsprechen die Dokumentanzahlen ungefähr dem Snapshot-Zeitpunkt?
Sind alle Primary Shards aktiv?
Sind die erwarteten Mappings und Aliase vorhanden?
Werden historische Ereignisse in Threat Hunting angezeigt?
Funktionieren Zeitfilter und Index Patterns beziehungsweise Data Views?
Enthalten aktuelle Indizes weiterhin neue Wazuh-Ereignisse?

Ein gelber Clusterzustand muss nicht zwingend auf einen fehlgeschlagenen Restore hinweisen. In einer Single-Node-Umgebung können nicht zugewiesene Replica Shards beispielsweise dazu führen, dass der Cluster dauerhaft yellow bleibt, obwohl alle Primary Shards verfügbar sind.

Lessons Learned / Best Practices

Daten und Sicherheitskonfiguration getrennt behandeln

Wazuh-Alertdaten und die Security-Konfiguration des Indexers sollten als getrennte Wiederherstellungsbereiche betrachtet werden.

Alert- und Archivindizes können über Snapshot Restore zurückgespielt werden. Benutzer, Rollen, Zertifikate und Security-Plugin-Konfigurationen sollten dagegen separat gesichert und über die dafür vorgesehenen Administrationswerkzeuge wiederhergestellt werden.

Dadurch wird verhindert, dass ein Daten-Restore unbeabsichtigt das Sicherheitsmodell des Zielclusters verändert.

Global State standardmäßig nicht übernehmen

Für die meisten Wiederherstellungen von Wazuh-Daten ist der globale Clusterzustand nicht erforderlich. Insbesondere bei Migrationen in einen neu aufgebauten Cluster sollte die vorhandene Konfiguration des Zielsystems erhalten bleiben.

include_global_state: false sollte daher als sichere Standardvorgabe behandelt werden, sofern nicht ein vollständig getestetes Disaster-Recovery-Konzept ausdrücklich die Wiederherstellung des gesamten Clusterzustands vorsieht.

Restore regelmäßig testen

Ein Snapshot ist erst dann ein belastbares Backup, wenn seine Wiederherstellung erfolgreich getestet wurde.

Regelmäßige Restore-Tests sollten mindestens folgende Punkte abdecken:

Zugriff auf das Repository
Berechtigungen des Restore-Benutzers
Ausschluss interner Security-Indizes
Verhalten der Dashboard-Optionen
Namenskonflikte mit vorhandenen Indizes
benötigter Speicherplatz
Dauer der Wiederherstellung
Validierung der Wazuh-Daten im Dashboard

Tests sollten möglichst in einem separaten Cluster oder mit umbenannten Indizes erfolgen.

UI- und API-Aufrufe nicht als identisch voraussetzen

Eine grafische Oberfläche abstrahiert die zugrunde liegende REST-API. Checkboxen, vorausgewählte Optionen und versionsabhängige Standardwerte können dazu führen, dass ein anderer Request erzeugt wird als bei einem manuell getesteten API-Aufruf.

Bei abweichendem Verhalten sollte deshalb der funktionierende API-Request als Referenz dienen. Anschließend können die UI-Einstellungen Schritt für Schritt an dessen Parameter angeglichen werden.

Rollenprüfung systematisch durchführen

Auch wenn die Berechtigungen in diesem Fall nicht die eigentliche Ursache waren, bleiben sie ein wichtiger Bestandteil der Fehleranalyse.

Zu prüfen sind:

Welche Rolle enthält die Snapshot-Berechtigungen?
Ist der Benutzer direkt oder über eine Backend-Rolle zugeordnet?
Gilt das Mapping auf allen Indexer-Knoten?
Verwendet das Dashboard tatsächlich den erwarteten Benutzer?
Werden Snapshot- und Restore-Requests mit 401 oder 403 abgelehnt?

Funktioniert ein API-Aufruf mit denselben Zugangsdaten, kann der Fokus anschließend auf Request-Parameter, Indexauswahl und Dashboard-Optionen verlagert werden.

Versions- und Migrationsgrenzen beachten

Snapshots sollten bevorzugt zwischen kompatiblen Wazuh- und OpenSearch-Versionen wiederhergestellt werden. Bei größeren Versionssprüngen müssen die Kompatibilitätsregeln von OpenSearch und Apache Lucene berücksichtigt werden.

Eine vollständige Sicherheitskonfiguration aus einem älteren Cluster sollte nicht ungeprüft in eine neue Wazuh-Installation übernommen werden. Stabiler ist es, den Zielcluster sauber aufzubauen, Rollen und Zertifikate kontrolliert zu konfigurieren und ausschließlich die benötigten Datenindizes zu migrieren.

Fazit

Wenn ein Snapshot-Restore in Wazuh 4.14.1 über die REST-API funktioniert, über das Dashboard jedoch fehlschlägt, liegt die Ursache nicht zwangsläufig bei den Benutzerberechtigungen. Häufig unterscheiden sich die tatsächlich gesendeten Restore-Parameter.

Im beschriebenen Fall war die Wiederherstellung des globalen Clusterzustands in der Benutzeroberfläche aktiviert. Nach dem Deaktivieren dieser Option funktionierte der Restore auch im Dashboard.

Für einen sicheren Wazuh-Restore sollten der globale Zustand deaktiviert, interne Security-Indizes ausgeschlossen und möglichst nur die tatsächlich benötigten Wazuh-Datenindizes ausgewählt werden. Ein erfolgreicher Restore muss anschließend über Cluster Health, Shard-Zustand, Dokumentanzahl und die Wazuh-Module im Dashboard validiert werden.