Configuration

Wazuh Indexer shares the same configuration system as OpenSearch. Refer to the OpenSearch documentation for general information about configuration files and settings.

Configuration files

Wazuh Indexer bundles two main configuration files on each node:

/etc/wazuh-indexer/opensearch.yml - main configuration file for Wazuh Indexer. This file contains the settings for the Wazuh Indexer cluster, such as cluster name, node name, network settings, and more.
/etc/wazuh-indexer/jvm.options - configuration file for the Java Virtual Machine (JVM) that runs Wazuh Indexer. This file contains settings for the JVM, such as heap size, garbage collection, and more.

For production workloads, tune the following operating system and JVM settings on every Wazuh Indexer node before starting the service. The package installations create the wazuh-indexer service user; the settings below apply to that user and the host it runs on.

Note: All the commands in this section require root privileges.

JVM heap size

Wazuh Indexer runs on the Java Virtual Machine (JVM). The heap size determines how much memory the indexer can use for its internal data structures, caches, and request processing. Set it in the /etc/wazuh-indexer/jvm.options file.

Follow these recommendations when sizing the heap:

Set the initial heap size (-Xms) and the maximum heap size (-Xmx) to the same value. This prevents performance degradation caused by the JVM resizing the heap at runtime.
Set the heap to no more than 50% of the available system RAM. The other half is left for the operating system file system cache, which Wazuh Indexer relies on heavily.
Do not set the heap above approximately 32 GB. Above this threshold the JVM can no longer use compressed ordinary object pointers, which wastes memory and reduces performance.

For example, on a node with 8 GB of RAM, set the heap to 4 GB:

-Xms4g
-Xmx4g

Where:

-Xms4g sets the initial heap size to 4 GB.
-Xmx4g sets the maximum heap size to 4 GB.

Restart the service after changing the heap size:

systemctl restart wazuh-indexer

Memory locking

Configure Wazuh Indexer to lock its process address space into RAM so that none of the JVM is ever swapped out.

bootstrap.memory_lock: true is enabled by default in /etc/wazuh-indexer/opensearch.yml. No changes are needed for package installations.
Grant the wazuh-indexer service user permission to lock unlimited memory. The RPM and Debian packages already configure this for both systemd-based and SysVinit-based systems — no additional configuration is required for package installations.
- systemd: LimitMEMLOCK=infinity is set in the service file.
- SysVinit: ulimit -l unlimited is applied by the init script before starting the process.

Reload the service manager and restart Wazuh Indexer:

systemctl daemon-reload
systemctl restart wazuh-indexer

Verify that memory locking is active by checking that the mlockall value is true:
```
curl -k -u <INDEXER_USERNAME>:<INDEXER_PASSWORD> "https://<INDEXER_IP_ADDRESS>:9200/_nodes?filter_path=**.mlockall&pretty"
```
```
{
  "nodes" : {
    "sRuGbIQRRfC54wzwIHjJWQ" : {
      "process" : {
        "mlockall" : true
      }
    }
  }
}
```
If the output is false, memory locking failed and the following line appears in /var/log/wazuh-indexer/wazuh-indexer.log:
```
memory locking requested for wazuh-indexer process but memory is not locked
```
This usually means the wazuh-indexer user lacks the memlock permission. For systemd-based systems, confirm that LimitMEMLOCK=infinity is present in the service file, reload with systemctl daemon-reload, and restart the service. For SysVinit-based systems, confirm that step 2 was applied correctly.

Note: Enabling bootstrap.memory_lock causes the JVM to reserve all the memory it needs at startup, including native memory beyond the configured heap. Make sure the node has enough physical RAM for the heap plus this overhead, otherwise the service may fail to start.

Virtual memory

Wazuh Indexer uses memory-mapped files (mmapfs) to store its indices. The default operating system limit on memory map areas is too low for production use, which can cause the node to fail to start or run out of memory.

Set vm.max_map_count to at least 262144. To check the current value:

sysctl vm.max_map_count

To increase it permanently, add the following line to /etc/sysctl.conf:

vm.max_map_count=262144

Apply the change without rebooting:

sysctl -p

Note: When running Wazuh Indexer in a container, set vm.max_map_count on the host machine, not inside the container.

File descriptors

Wazuh Indexer uses a large number of file descriptors. Running out of them can lead to data loss, so increase the limit for the wazuh-indexer user to 65535 or higher.

The RPM and Debian packages already set this limit to 65535 through the systemd service, so no additional configuration is required for package installations. To raise the limit manually, create or edit a systemd service override:

mkdir -p /etc/systemd/system/wazuh-indexer.service.d/
cat > /etc/systemd/system/wazuh-indexer.service.d/override.conf << EOF
[Service]
LimitNOFILE=65535
EOF

Reload and restart the service:

systemctl daemon-reload
systemctl restart wazuh-indexer

Verify the limit applied to the running node by checking max_file_descriptors:

curl -k -u <INDEXER_USERNAME>:<INDEXER_PASSWORD> "https://<INDEXER_IP_ADDRESS>:9200/_nodes/stats/process?filter_path=**.max_file_descriptors&pretty"

Wazuh Indexer technical documentation