Configuration files

1. Wazuh Manager Configuration

wazuh-manager.conf: The main configuration file for the Wazuh manager. It controls rules, decoders, agent enrollment, active responses, clustering, and more.
- Customization: Mount a custom wazuh-manager.conf or specific configuration snippets (e.g., local rules in local_rules.xml) into the manager container at /wazuh-mount-point/, which will be copied to the path /var/wazuh-manager (e.g., the file /var/wazuh-manager/etc/wazuh-manager.conf must be mounted at /wazuh-mount-point/etc/wazuh-manager.conf) .

2. Wazuh Indexer Configuration

opensearch.yml: The primary configuration file for OpenSearch. Controls cluster settings, network binding, path settings, discovery, memory allocation, etc.
- Customization: Mount a custom opensearch.yml into the indexer container(s) at /usr/share/wazuh-indexer/config/opensearch.yml.
JVM Settings (jvm.options): Manages Java Virtual Machine settings, especially heap size (-Xms, -Xmx). Critical for performance and stability.
- Customization: Mount a custom jvm.options file or set OPENSEARCH_JAVA_OPTS environment variable.

3. Wazuh Dashboard (OpenSearch Dashboards) Configuration

opensearch_dashboards.yml: The main configuration file for OpenSearch Dashboards. Controls server host/port, OpenSearch connection URL, SSL settings, and Wazuh plugin settings.
- Customization: Mount a custom opensearch_dashboards.yml into the dashboard container at /usr/share/wazuh-dashboard/config/opensearch_dashboards.yml and custom wazuh.yml into the dashboard container at /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml .
Wazuh Plugin Settings: The Wazuh plugin for the dashboard has its own configuration, often within opensearch_dashboards.yml or managed through environment variables, specifying the Wazuh API URL and credentials.
opensearch_dashboards.keystore: Secure storage for the dashboard secrets, located at /usr/share/wazuh-dashboard/config/opensearch_dashboards.keystore. The image is shipped without a keystore; the container entrypoint creates it on the first start and adds a randomly generated wazuh_ai_assistant.encryptionKey, which the AI assistant uses to encrypt its data. The opensearch.username and opensearch.password entries are set on every start from the DASHBOARD_USERNAME and DASHBOARD_PASSWORD environment variables.
- Customization: To set your own key, add it through the keystore tool inside the dashboard container and restart the service:
```
echo "<your-encryption-key>" | docker compose exec -T wazuh.dashboard \
  /usr/share/wazuh-dashboard/bin/opensearch-dashboards-keystore add wazuh_ai_assistant.encryptionKey --stdin --allow-root -f
docker compose restart wazuh.dashboard
```
- Important: The keystore is created only when it does not already exist, so the encryption key stays stable across restarts as long as the /usr/share/wazuh-dashboard/config volume is kept. If the keystore is deleted, the entrypoint generates a new key on the next start and any data encrypted with the previous one becomes unreadable.

Applying Configuration Changes

Modify docker-compose.yml:
- For changes to environment variables, port mappings, or volume mounts.
- After changes, you typically need to stop and restart the containers:
```
docker compose down
docker compose up -d
```

Consult the official Wazuh documentation for version 5.0.0 for detailed information on all possible configuration parameters for each component.

Persistence configuration

When customizing your Wazuh Docker deployment, certain files and directories must be persisted to retain your changes across container restarts and recreations. This is critical for maintaining custom configurations, user credentials, and security settings.

Volumes and Bind Mounts

Docker volumes allow you to persist data outside of container lifecycles. When a container is removed or recreated, data stored in volumes remains intact. This is essential for maintaining configuration files, user data, and other persistent state. While, bind mounts allow you to mount a file or directory from the host into the container.

To persist files or directories in your Wazuh deployment, you can mount them as volumes or bind mounts in your docker-compose.yml file.

Important

: Ensure that files exist on the host before starting the containers. If the file doesn't exist, Docker will create a directory instead, which may cause startup failures.

Wazuh Dashboard keystore

The docker-compose.yml files mount the named volume wazuh-dashboard-config on /usr/share/wazuh-dashboard/config, which is where opensearch_dashboards.keystore is stored. Keeping this volume preserves the wazuh_ai_assistant.encryptionKey generated on the first start.

Removing the volume (for example, with docker compose down -v) deletes the keystore. The next start creates a new one with a different encryption key, and data encrypted by the AI assistant with the previous key can no longer be decrypted.

For more information on Docker volumes and bind mounts, refer to the official Docker documentation:

5.3 KiB Raw Blame History