Setup module

The Setup module prepares and maintains the storage resources required by the Wazuh indexer. These resources include:

During startup, the module creates or updates the index templates, data streams, ISM policies, and internal indices that Wazuh requires. This ensures that the storage layer is ready before Wazuh begins indexing data.

The Setup module is installed by default with the Wazuh indexer packages as wazuh-indexer-setup. You can verify that the module is installed by running the following command:

# /usr/share/wazuh-indexer/bin/opensearch-plugin list | grep "wazuh-indexer-setup"

Output

wazuh-indexer-setup

Initialization process

When the Wazuh indexer starts, the Setup module verifies that all required Wazuh storage resources are available. It creates any missing resources and updates Wazuh-managed index templates to match the version included with the installed Wazuh release.

Note

Manual changes to Wazuh-managed index templates can be overwritten when the Wazuh indexer restarts.

Initialization retry mechanism

The Setup module retries initialization tasks when temporary failures occur during startup. After an operation fails, the module waits for the configured backoff interval before retrying.

By default, the module retries a failed initialization task once. If the retry also fails, the module stops the initialization process and shuts down the node. This prevents the node from running with incomplete storage resources. You can set the number of retries with the plugins.setup.max_retries setting and the interval between them with the plugins.setup.backoff setting, in the /etc/wazuh-indexer/opensearch.yml file.

Replica configuration

When configured, the Setup module applies cluster.default_number_of_replicas as a persistent cluster setting. This gives Wazuh-managed indices a consistent default replica count across the cluster without requiring individual index configuration.

Configuration

The Setup module settings are configured in the /etc/wazuh-indexer/opensearch.yml file using the plugins.setup prefix. Changes take effect after you restart the Wazuh indexer.

Setting	Default	Description
`plugins.setup.timeout`	`30`	Timeout, in seconds, for index and search operations. Valid range: 5-120.
`plugins.setup.backoff`	`15`	Delay, in seconds, between initialization retry attempts. Valid range: 5-60.
`plugins.setup.max_retries`	`1`	Number of times the module retries a failed initialization task before it shuts down the node. `0` disables retries. Valid range: 0-10.
`plugins.setup.settings_update.enabled`	`true`	Allows changes through the `PUT /_plugins/_setup/settings` endpoint. When `false`, the endpoint returns `403` for every caller, regardless of role.

API reference

The Setup module exposes REST API endpoints under /_plugins/_setup/.

Note

All API requests require authentication.

Update settings

Update settings are stored in the .wazuh-settings index on the Wazuh indexer. Currently, the Wazuh indexer API supports the engine.index_raw_events setting, which controls whether raw events are indexed into the wazuh-events-raw-v5 data stream. The default value is false, so Wazuh does not index raw events until you enable the setting.

Request

PUT /_plugins/_setup/settings

Request body:

{
  "engine": {
    "index_raw_events": true
  }
}

Where:

Field	Required	Description
`engine`	Yes	Engine configuration object.
`engine.index_raw_events`	Yes	Enables (`true`) or disables (`false`) the indexing of raw events. The default is `false`.

Example

Replace <WAZUH_INDEXER_IP> with the IP address of the Wazuh indexer node and <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD> with your Wazuh indexer username and password.

curl -sk -u <WAZUH_INDEXER_USERNAME>:<WAZUH_INDEXER_PASSWORD>  -X PUT \
"https://<WAZUH_INDEXER_IP>:9200/_plugins/_setup/settings" \
-H 'Content-Type: application/json' \
-d '{
  "engine": {
    "index_raw_events": true
  }
}'

Responses

// Success
{
  "message": "Settings updated successfully.",
  "status": 200
}

// Missing field
{
  "message": "Missing required field: 'engine.index_raw_events'.",
  "status": 400
}

// Invalid type
{
  "message": "Field 'engine.index_raw_events' must be of type boolean.",
  "status": 400
}

// Settings updates disabled
{
  "message": "Setup settings updates are disabled on this deployment.",
  "status": 403
}

The status codes in the responses have the following meanings:

Code	Description
`200`	Settings updated successfully.
`400`	Invalid request body, missing required fields, or invalid field type.
`403`	Settings updates are disabled on this node, because `plugins.setup.settings_update.enabled` is `false`.
`500`	Internal server error.