Wazuh indexer

Migrate the Wazuh indexer configuration

Perform the following steps on every Wazuh indexer node of the new Wazuh 5.x cluster.

1. Stop the Wazuh indexer service:

   # systemctl stop wazuh-indexer
   

2. Review the Wazuh 4.x configuration and recreate the required settings manually in the corresponding Wazuh 5.x files.

3. Update or remove the Wazuh 4.x settings that changed in Wazuh 5.x:

   Setting	Wazuh 5.x change
   compatibility.override_main_response_version	Removed. The Wazuh indexer doesn't start if opensearch.yml contains this setting.
   opensearch_performance_analyzer.*, plugins.anomaly_detection.*, plugins.asynchronous_search.*, plugins.ml_commons.*, plugins.query.datasources.*, plugins.neural_search.*, knn.*	Removed. Wazuh indexer 5.x doesn't include the related plugins. Also remove the settings of the opensearch-observability plugin (observability and notebooks), which Wazuh indexer 5.x no longer includes.
   cluster.initial_master_nodes	Renamed to cluster.initial_cluster_manager_nodes, which the Wazuh 5.x opensearch.yml already sets. Copy the node list to the new setting and don't add the old one.
   plugins.security.ssl.transport.enforce_hostname_verification, plugins.security.ssl.transport.resolve_hostname	Renamed to transport.ssl.enforce_hostname_verification and transport.ssl.resolve_hostname, which the Wazuh 5.x opensearch.yml already sets. Don't add the Wazuh 4.x settings: the Wazuh indexer doesn't start if opensearch.yml defines both the old and the new name of a setting. transport.ssl.enforce_hostname_verification is true in Wazuh 5.x (it was false in Wazuh 4.x), so each node certificate must include the node address in its subject alternative names. transport.ssl.resolve_hostname remains false.
   plugins.security.authcz.admin_dn, plugins.security.nodes_dn	The distinguished name (DN) attribute order differs. Keep the values that the Wazuh 5.x package generated. If you keep the Wazuh 4.x certificates, set them to the subjects of those certificates.
   plugins.security.ssl.* certificate paths	The Wazuh 5.x package names the node certificate indexer.pem and indexer-key.pem. To keep the Wazuh 4.x certificates, copy them to /etc/wazuh-indexer/certs/ as indexer.pem, indexer-key.pem, admin.pem, admin-key.pem, and root-ca.pem, so the Wazuh 5.x paths stay valid. To keep the certificates that the Wazuh 5.x package issued, don't change the paths.
   Multi-tenancy settings	Disabled by default in Wazuh 5.x.
   plugins.security.ssl.http.enabled_ciphers, plugins.security.ssl.http.enabled_protocols	Not set in Wazuh 5.x, which uses the OpenSearch defaults. The Wazuh 4.x installation assistant restricted them to TLS 1.2 and four cipher suites. Copy them only if your security policy requires a restricted list.
   plugins.security.system_indices.indices	The Wazuh 5.x list drops the indices of the removed plugins and adds .wazuh-internal-state. Keep the Wazuh 5.x values.

4. Review any custom JVM and logging configuration before you apply it to the Wazuh 5.x deployment. Copy only individual non-default lines into the Wazuh 5.x jvm.options and log4j2.properties files instead of replacing them.

5. Edit the security configuration files as described in the Wazuh indexer security configuration section. Apply the configuration after you start the Wazuh indexer service on every node, as described in Apply the security configuration.

6. Start the Wazuh indexer service:

   # systemctl start wazuh-indexer
   

7. After the Wazuh indexer service is running on every node and you have applied the security configuration, verify that the nodes have joined the cluster.

   $ curl -k -u <USERNAME>:<PASSWORD> \
     https://<WAZUH_INDEXER_IP>:9200/_cat/nodes?v
   

   Where:

   • <USERNAME>: is the username of a Wazuh indexer user with permissions to query the cluster.

   • <PASSWORD>: is the password of the specified Wazuh indexer user.

   • <WAZUH_INDEXER_IP>: is the IP address or hostname of a Wazuh indexer node in the Wazuh 5.x cluster. In an all-in-one deployment, use 127.0.0.1.

   Note

   Retrieve the generated WAZUH_INDEXER_ADMIN_PASSWORD from /etc/wazuh-indexer/export/credentials.env on the Wazuh indexer node. To print only the value, run grep '^WAZUH_INDEXER_ADMIN_PASSWORD=' /etc/wazuh-indexer/export/credentials.env | cut -d= -f2- on the Wazuh indexer node.

Apply the security configuration

After you recreate the required security configuration, apply the changes to the Wazuh indexer. Make the same changes to the files in /etc/wazuh-indexer/opensearch-security/ on every Wazuh indexer node.

1. Restart the Wazuh indexer service on every node:

   # systemctl restart wazuh-indexer
   

2. Apply the security configuration. Run the script once, from a single node whose files contain all the changes, after the Wazuh indexer service is running on every node. The Wazuh indexer stores the security configuration in its security index, so the change reaches every node:

   # /usr/share/wazuh-indexer/bin/indexer-security-init.sh
   

   Warning

   Running indexer-security-init.sh loads the security configuration from /etc/wazuh-indexer/opensearch-security/ into the Wazuh indexer security index. This can overwrite security settings previously configured through the Wazuh dashboard or security API. Ensure that the configuration files contain the security settings you want to retain before running the script. Running the script later from a node whose files lack the recreated users, roles, or role mappings removes them from the whole cluster, and the affected users can no longer log in. Keep the files in /etc/wazuh-indexer/opensearch-security/ identical on every node.

3. Verify that authentication works. Log in to the Wazuh dashboard and confirm that users can authenticate and access the resources their assigned roles permit. Also verify each external authentication backend, such as LDAP or SAML, against every Wazuh indexer node before you point production traffic at the Wazuh 5.x cluster.

Setting up a shared file system

Perform the following steps on a server that is accessible from both the Wazuh 4.x and Wazuh 5.x indexer clusters.

Set up a snapshot repository on Wazuh 4.x

On the Wazuh 4.x dashboard, perform the following steps:

1. Click the ☰ menu, navigate to Indexer management > Snapshot Management > Repositories, and select Create repository to create a new snapshot repository.

2. Enter a Repository name, such as wazuh-4x-migration, select the repository type Shared file system, enter the repository Location /mnt/snapshots, and select Add to register the new repository.

   

Take a snapshot of the Wazuh 4.x indices

On the Wazuh 4.x dashboard, perform the following steps:

1. Click the ☰ menu, navigate to Indexer management > Snapshot Management > Snapshots.

2. Select Take snapshot and enter a Snapshot name.

3. Select the Wazuh data indices that you want to migrate from the list. The Wazuh 4.x dashboard ignores index patterns that you type in this field and includes every index in the snapshot.

   Warning

   Do not include system indices or the cluster state in the migration snapshot. The snapshot is intended to transfer Wazuh 4.x historical data to the new Wazuh 5.x deployment, not the Wazuh 4.x indexer configuration. Before you restore the snapshot, verify that it contains only the Wazuh data indices you selected.

4. Select the repository you created earlier to store the snapshots.

5. Ensure Include cluster state in snapshots is not selected in the Advanced options to prevent the snapshot from including cluster-level configuration.

6. Click Add to create a new snapshot. The snapshot files are saved in the repository location /mnt/snapshots.

   
   

Set up a snapshot repository on Wazuh 5.x

Run the command below on the Wazuh 5.x indexer node to set up a read-only snapshot repository:

# curl -k -X PUT \
  --cert /etc/wazuh-indexer/certs/admin.pem \
  --key /etc/wazuh-indexer/certs/admin-key.pem \
  "https://<WAZUH_INDEXER_IP>:9200/_snapshot/wazuh-4x-migration" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "fs",
    "settings": {
      "location": "/mnt/snapshots",
      "readonly": true
    }
  }'

The command output looks similar to this:

{"acknowledged":true}

Replace <WAZUH_INDEXER_IP> with the IP address of the Wazuh 5.x indexer. In an all-in-one deployment, use 127.0.0.1 because the Wazuh indexer listens on the loopback address.

Restore the snapshot on Wazuh 5.x

Perform the following steps on the Wazuh 5.x deployment.

1. On the Wazuh dashboard, navigate to Indexer management > Snapshot Management > Snapshots. The snapshot created on the Wazuh 4.x deployment is available to the Wazuh 5.x deployment through the shared /mnt/snapshots repository. Select the migration snapshot, then click Restore.

   

2. Click Restore snapshot.

   

   Note

   You can choose to restore specific indices or rename the indices. In the image above, we add the prefix restored_ to the restored index names.

   Warning

   Do not restore system indices or the global cluster state into the Wazuh 5.x deployment (for example, .kibana*, .opendistro*).

3. Navigate to Indexer management > Indexes on the Wazuh dashboard, and filter with the prefix restored_ to view the restored indices.

   

4. Create an index pattern to retrieve the indices' data. On the Wazuh dashboard, navigate to Dashboards Management > Index patterns, then click Create index pattern.

   

5. Set the Index pattern name, then click Next step. In the image below, the index pattern name is restored_wazuh*. Enter restored_wazuh as the name, because the dashboard adds the trailing * itself.

   

6. Set the Time field. From the drop-down menu, select timestamp, then click Create index pattern.

   

7. Click the ☰ menu, navigate to Discover on the Wazuh dashboard to verify that the migrated indices are available. Select the Index pattern (restored_wazuh*) created in the previous step to view the migrated index data.

   

From the Discover page, you can explore and search the migrated index data using the Wazuh dashboard.