From f7efef25d7cf19e201a083700d3d65af598d0aae Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Wed, 11 Feb 2026 08:21:37 -0500 Subject: [PATCH 1/6] Enhance docker docs structure --- docs/README.md | 2 +- docs/SUMMARY.md | 12 ++- docs/ref/backup-and-restore.md | 89 +++++++++++++++++++ docs/ref/configuration/change-passwords.md | 45 ++++++++++ docs/ref/getting-started/getting-started.md | 2 +- docs/ref/introduction/compatibility.md | 22 +++++ .../description.md | 0 .../introduction.md | 0 docs/ref/performance.md | 42 +++++++++ docs/ref/security.md | 26 ++++++ docs/ref/uninstall.md | 55 ++++++++++++ 11 files changed, 290 insertions(+), 5 deletions(-) create mode 100644 docs/ref/backup-and-restore.md create mode 100644 docs/ref/configuration/change-passwords.md create mode 100644 docs/ref/introduction/compatibility.md rename docs/ref/{Introduction => introduction}/description.md (100%) rename docs/ref/{Introduction => introduction}/introduction.md (100%) create mode 100644 docs/ref/performance.md create mode 100644 docs/ref/security.md create mode 100644 docs/ref/uninstall.md diff --git a/docs/README.md b/docs/README.md index acb98674..5753e69f 100644 --- a/docs/README.md +++ b/docs/README.md @@ -89,7 +89,7 @@ The folder `wazuh-agent` contains a README explaining how to run a container wit │   │   │   ├── README.md │   │   │   └── requirements.md │   │   ├── glossary.md - │   │   ├── Introduction + │   │   ├── introduction │   │   │   ├── compatibility.md │   │   │   ├── description.md │   │   │   └── README.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index be59f772..ea420356 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -12,8 +12,9 @@ # Reference Manual -- [Introduction](ref/Introduction/introduction.md) - - [Description](ref/Introduction/description.md) +- [Introduction](ref/introduction/introduction.md) + - [Description](ref/introduction/description.md) + - [Compatibility](ref/introduction/compatibility.md) - [Getting Started](ref/getting-started/getting-started.md) - [Requirements](ref/getting-started/requirements.md) - [Deployment](ref/getting-started/deployment/deployment.md) @@ -23,5 +24,10 @@ - [Configuration](ref/configuration/configuration.md) - [Environment Variabless](ref/configuration/environment-variables.md) - [Configuration files](ref/configuration/configuration-files.md) + - [Change passwords](ref/configuration/change-passwords.md) - [Upgrade](ref/upgrade.md) -- [Glossary](ref/glossary.md) \ No newline at end of file +- [Uninstall](ref/uninstall.md) +- [Backup and restore](ref/backup-and-restore.md) +- [Security](ref/security.md) +- [Performance](ref/performance.md) +- [Glossary](ref/glossary.md) diff --git a/docs/ref/backup-and-restore.md b/docs/ref/backup-and-restore.md new file mode 100644 index 00000000..542f786d --- /dev/null +++ b/docs/ref/backup-and-restore.md @@ -0,0 +1,89 @@ +# Backup and restore + +On construction... + + diff --git a/docs/ref/configuration/change-passwords.md b/docs/ref/configuration/change-passwords.md new file mode 100644 index 00000000..566c4bcc --- /dev/null +++ b/docs/ref/configuration/change-passwords.md @@ -0,0 +1,45 @@ +# Change passwords + +This section describes how to rotate the credentials used by the provided Docker Compose deployments. + +## Scope + +The Compose files include the following password-controlled integrations: + +- **Wazuh Indexer access (Manager and Dashboard clients)**: `INDEXER_USERNAME`, `INDEXER_PASSWORD` +- **Wazuh Dashboard login**: `DASHBOARD_USERNAME`, `DASHBOARD_PASSWORD` +- **Wazuh API access (Dashboard client)**: `API_USERNAME`, `API_PASSWORD` + +For variable descriptions, see [Environment variables](environment-variables.md). + +## Rotate credentials + +1. Navigate to your deployment directory: + + - `single-node/` (single-node stack) + - `multi-node/` (multi-node stack) + +2. Edit the deployment `docker-compose.yml` and update the required values under `environment`: + + - Single-node: update `wazuh.manager` and `wazuh.dashboard`. + - Multi-node: update `wazuh.master`, `wazuh.worker`, and `wazuh.dashboard`. + + Ensure `INDEXER_USERNAME` and `INDEXER_PASSWORD` are consistent anywhere they are defined. + +3. Recreate the containers to apply the new values: + + ```bash + docker compose down + docker compose up -d + ``` + +4. Validate access: + + - Log in to the Dashboard with the updated credentials. + - Confirm the Dashboard can query data (indirectly validating the Indexer and API credentials). + +## Notes + +- The Manager applies `API_USERNAME` / `API_PASSWORD` at startup by creating or updating the API user. +- The Dashboard regenerates its OpenSearch Dashboards keystore on startup; changes take effect after the container is recreated. +- Rotating Indexer credentials requires updating both the Indexer user configuration and the Compose client variables (`INDEXER_*`). diff --git a/docs/ref/getting-started/getting-started.md b/docs/ref/getting-started/getting-started.md index 677a16ef..5aed6620 100644 --- a/docs/ref/getting-started/getting-started.md +++ b/docs/ref/getting-started/getting-started.md @@ -18,7 +18,7 @@ Getting started with Wazuh-Docker involves the following general steps: Before diving into the deployment, please ensure you have reviewed: -- The [Description](ref/Introduction/description.md) of Wazuh-docker to understand the components and architecture. +- The [Description](ref/introduction/description.md) of Wazuh-docker to understand the components and architecture. - The [Requirements](ref/getting-started/requirements.md) to confirm your environment is suitable. ## Steps to Get Started diff --git a/docs/ref/introduction/compatibility.md b/docs/ref/introduction/compatibility.md new file mode 100644 index 00000000..4c6721a0 --- /dev/null +++ b/docs/ref/introduction/compatibility.md @@ -0,0 +1,22 @@ +# Compatibility + +This section provides information about the compatibility of the Wazuh Docker stack with different platforms. + +## Supported platforms + +### Host operating system and architecture + +- Linux hosts are recommended for running the stack. +- Windows and macOS are supported when using Docker Desktop. On Windows, the WSL 2 backend is recommended. +- When building images, the build process supports `linux/amd64` and `linux/arm64`. + +### Privileged ports and rootless Docker + +The default Compose deployments publish some privileged ports on the host (for example, the Dashboard on `443/tcp` and syslog on `514/udp`). + +- If you run Docker in rootless mode or under restrictive policies, publishing ports below `1024` may fail. +- In such environments, map the services to non-privileged host ports in the corresponding `docker-compose.yml` file. + +### Resource constraints + +For detailed information on resource requirements and recommendations, please refer to the [Requirements](../getting-started/requirements.md) section. diff --git a/docs/ref/Introduction/description.md b/docs/ref/introduction/description.md similarity index 100% rename from docs/ref/Introduction/description.md rename to docs/ref/introduction/description.md diff --git a/docs/ref/Introduction/introduction.md b/docs/ref/introduction/introduction.md similarity index 100% rename from docs/ref/Introduction/introduction.md rename to docs/ref/introduction/introduction.md diff --git a/docs/ref/performance.md b/docs/ref/performance.md new file mode 100644 index 00000000..7a0f8653 --- /dev/null +++ b/docs/ref/performance.md @@ -0,0 +1,42 @@ +# Performance + +This section provides practical recommendations to improve performance for Wazuh Docker deployments (single-node and multi-node). Apply the controls that match your workload and environment. + +## Performance drivers + +- **Wazuh Indexer** is typically the main bottleneck (JVM heap, disk I/O, and CPU). +- **Wazuh Manager** load grows with the number of connected agents and event throughput. +- **Wazuh Dashboard** mainly affects interactive usage and depends on Indexer responsiveness. + +For baseline host sizing and prerequisites, see [Requirements](getting-started/requirements.md). + +## Storage and host + +- Use low-latency storage for the Indexer data volume (see [Requirements](getting-started/requirements.md)). +- Avoid slow or inconsistent storage for the Indexer (for example, network filesystems) unless you have validated latency and durability for your use case. +- Monitor disk space growth. Index data and persistent volumes can grow quickly in high-ingest environments. + +## Wazuh Indexer (OpenSearch) + +- Set the JVM heap explicitly using `OPENSEARCH_JAVA_OPTS` (documented in [Environment variables](configuration/environment-variables.md)). +- Keep heap sizing conservative relative to available memory so the OS can cache filesystem data; oversized heap commonly degrades disk-heavy workloads. +- Ensure the Linux host meets the required `vm.max_map_count` prerequisite (documented in [Requirements](getting-started/requirements.md)). +- Prioritize heap sizing and GC stability. +- Prioritize disk throughput/latency for the Indexer data volume. +- Prioritize CPU availability during ingest peaks. + +## Wazuh Manager + +- If you observe ingestion backpressure or delayed processing, validate that the Manager has sufficient CPU and memory and that persistent volumes are not constrained by slow storage. +- For multi-node deployments, distribute agent load appropriately (for example, by separating responsibilities between master/worker nodes) to avoid overloading. + +## Dashboard + +- Dashboard responsiveness depends on Indexer health. Address Indexer resource constraints first when troubleshooting slow UI queries. +- Avoid exposing the Dashboard to excessive concurrent users on small hosts; scale the host or deployment model if needed. + +## Observability and troubleshooting + +- Start with container-level signals: `docker stats`, container logs, and host disk utilization. +- For Indexer issues, validate basic cluster health and look for sustained CPU saturation, JVM memory pressure, and disk I/O contention. +- For Manager issues, review Manager logs for queue growth and repeated connection retries. diff --git a/docs/ref/security.md b/docs/ref/security.md new file mode 100644 index 00000000..e2bd8e4a --- /dev/null +++ b/docs/ref/security.md @@ -0,0 +1,26 @@ +# Security + +This section summarizes security recommendations for Wazuh Docker deployments (single-node and multi-node). Apply the controls that match your environment and risk profile. + +## Credentials and secrets + +- Do not use default credentials. The Compose examples include placeholder values for the Wazuh API, Dashboard, and Indexer access. +- Prefer injecting secrets at runtime (for example, via your CI/CD secret store or an external secrets manager) instead of hardcoding them in `docker-compose.yml`. +- Rotate credentials regularly and after any suspected exposure. + +## Certificates and TLS + +- Protect the generated `wazuh-certificates/` directory. Limit filesystem permissions and do not publish it. +- Regenerate certificates if private keys are leaked or if nodes are re-provisioned. +- Use certificates and TLS settings appropriate for production (trusted CA, correct DNS names, and key protection). + +## Network exposure + +- Restrict access to exposed service ports at the host firewall and security group level. +- Do not expose internal-only endpoints to untrusted networks. In particular, limit access to the Indexer API port (`9200`) and the Wazuh API port (`55000`) to administrative networks. + +## Host and runtime hardening + +- Run Docker on a hardened host (patched OS, minimal installed packages, restricted SSH access). +- Limit access to the Docker daemon. Docker socket access grants administrative control over the host. +- Ensure persistent volumes and bind-mounted configuration files are backed by secure storage and appropriate permissions. diff --git a/docs/ref/uninstall.md b/docs/ref/uninstall.md new file mode 100644 index 00000000..d2fafc1e --- /dev/null +++ b/docs/ref/uninstall.md @@ -0,0 +1,55 @@ +# Uninstall + +This section describes how to uninstall a Wazuh Docker deployment by stopping and removing the resources created. + +## Uninstalling single-node and multi-node deployments + +1. Navigate to the deployment directory (`single-node` or `multi-node`): + + ```bash + cd + ``` + +2. Stop and remove the containers: + + ```bash + docker compose down --remove-orphans + ``` + +3. Remove persistent volumes and all stored data: + + ```bash + docker compose down --volumes --remove-orphans + ``` + +4. Remove generated or downloaded files: + + ```bash + rm -rf wazuh-certificates/ config.yml wazuh-certs-tool.sh + ``` + +5. Verify that the deployment is removed: + + ```bash + docker ps + ``` + +## Wazuh agent deployment + +1. Navigate to the agent deployment directory: + + ```bash + cd wazuh-agent + ``` + +2. Stop and remove the container: + + ```bash + docker compose down --remove-orphans + ``` + +3. Verify that the deployment is removed: + + ```bash + docker ps + ``` From 5f7576ce16f9ea739da6c90bdf93acd841744c62 Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Wed, 11 Feb 2026 08:23:14 -0500 Subject: [PATCH 2/6] Add changelog --- CHANGELOG.md | 1 + 1 file changed, 1 insertion(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 4461fd73..c1bcf9a9 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,6 +9,7 @@ All notable changes to this project will be documented in this file. ### Changed +- Add missing documentation sections in the repository ([#2215](https://github.com/wazuh/wazuh-docker/pull/2215)) - Add Wazuh version and revision into wazuh-certs-tool and config file ([#2195](https://github.com/wazuh/wazuh-docker/pull/2195)) - Improve S3 artifact URLs handling ([#2183](https://github.com/wazuh/wazuh-docker/pull/2183)) - Allow building separate targets ([#2177](https://github.com/wazuh/wazuh-docker/pull/2177)) From 5f625d4bd55fc022e1b6ab55833d677023aa5517 Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Thu, 12 Feb 2026 12:50:51 -0500 Subject: [PATCH 3/6] Update docs to meet new requirements --- docs/SUMMARY.md | 2 +- docs/ref/backup-and-restore.md | 89 +--------------------- docs/ref/configuration/change-passwords.md | 45 ----------- docs/ref/configuration/persistence.md | 77 +++++++++++++++++++ docs/ref/upgrade.md | 79 +++++++++++++++++-- 5 files changed, 155 insertions(+), 137 deletions(-) delete mode 100644 docs/ref/configuration/change-passwords.md create mode 100644 docs/ref/configuration/persistence.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index ea420356..5a09ca0a 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -24,7 +24,7 @@ - [Configuration](ref/configuration/configuration.md) - [Environment Variabless](ref/configuration/environment-variables.md) - [Configuration files](ref/configuration/configuration-files.md) - - [Change passwords](ref/configuration/change-passwords.md) + - [Persistence](ref/configuration/persistence.md) - [Upgrade](ref/upgrade.md) - [Uninstall](ref/uninstall.md) - [Backup and restore](ref/backup-and-restore.md) diff --git a/docs/ref/backup-and-restore.md b/docs/ref/backup-and-restore.md index 542f786d..d9179b67 100644 --- a/docs/ref/backup-and-restore.md +++ b/docs/ref/backup-and-restore.md @@ -1,89 +1,6 @@ # Backup and restore -On construction... +For backup and restore, refer to the documentation for each component: - +- [Wazuh central components](https://documentation.wazuh.com/current/migration-guide/index.html) +- [Wazuh agent](https://documentation.wazuh.com/current/migration-guide/index.html) diff --git a/docs/ref/configuration/change-passwords.md b/docs/ref/configuration/change-passwords.md deleted file mode 100644 index 566c4bcc..00000000 --- a/docs/ref/configuration/change-passwords.md +++ /dev/null @@ -1,45 +0,0 @@ -# Change passwords - -This section describes how to rotate the credentials used by the provided Docker Compose deployments. - -## Scope - -The Compose files include the following password-controlled integrations: - -- **Wazuh Indexer access (Manager and Dashboard clients)**: `INDEXER_USERNAME`, `INDEXER_PASSWORD` -- **Wazuh Dashboard login**: `DASHBOARD_USERNAME`, `DASHBOARD_PASSWORD` -- **Wazuh API access (Dashboard client)**: `API_USERNAME`, `API_PASSWORD` - -For variable descriptions, see [Environment variables](environment-variables.md). - -## Rotate credentials - -1. Navigate to your deployment directory: - - - `single-node/` (single-node stack) - - `multi-node/` (multi-node stack) - -2. Edit the deployment `docker-compose.yml` and update the required values under `environment`: - - - Single-node: update `wazuh.manager` and `wazuh.dashboard`. - - Multi-node: update `wazuh.master`, `wazuh.worker`, and `wazuh.dashboard`. - - Ensure `INDEXER_USERNAME` and `INDEXER_PASSWORD` are consistent anywhere they are defined. - -3. Recreate the containers to apply the new values: - - ```bash - docker compose down - docker compose up -d - ``` - -4. Validate access: - - - Log in to the Dashboard with the updated credentials. - - Confirm the Dashboard can query data (indirectly validating the Indexer and API credentials). - -## Notes - -- The Manager applies `API_USERNAME` / `API_PASSWORD` at startup by creating or updating the API user. -- The Dashboard regenerates its OpenSearch Dashboards keystore on startup; changes take effect after the container is recreated. -- Rotating Indexer credentials requires updating both the Indexer user configuration and the Compose client variables (`INDEXER_*`). diff --git a/docs/ref/configuration/persistence.md b/docs/ref/configuration/persistence.md new file mode 100644 index 00000000..af8c9af9 --- /dev/null +++ b/docs/ref/configuration/persistence.md @@ -0,0 +1,77 @@ +# 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. + +## Wazuh Indexer + +### Internal Users + +The `internal_users.yml` file contains the initial users and passwords for the Wazuh Indexer. This file is not included by default in the repository and must be created manually if you wish to customize internal users or update passwords. + +#### Creating the Configuration File + +1. Create the directory: + ```bash + mkdir -p ./config/wazuh_indexer/ + ``` + +2. Create the file: Create `./config/wazuh_indexer/internal_users.yml` with your user definitions. Here is a basic example: + ```yaml + --- + # This is the internal user database + # The hash value is a bcrypt hash and can be generated with /usr/share/wazuh-indexer/plugins/opensearch-security/tools/hash.sh + + _meta: + type: "internalusers" + config_version: 2 + + # Default users + + admin: + hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG" + reserved: true + backend_roles: + - "admin" + description: "Admin user" + + kibanaserver: + hash: "$2a$12$4AcgAt3xwOWadA5s5blL6ev39OXDNhmOesEoo33eZtrq2N0YrU3H." + reserved: true + description: "Kibana server user" + ``` + +> **Important**: This example includes the default `admin` and `kibanaserver` users with their default passwords (hashed). These users are required for the standard `docker-compose.yml` configuration (e.g., `INDEXER_USERNAME=admin` and `DASHBOARD_USERNAME=kibanaserver`) to function correctly. If you change these passwords, you must also update the corresponding environment variables in your `docker-compose.yml`. + +#### Docker Compose Configuration + +To persist the `internal_users.yml` file, add a volume mount to your `docker-compose.yml` for the `wazuh.indexer` service: + +```yaml +services: + wazuh.indexer: + volumes: + - ./config/wazuh_indexer/internal_users.yml:/usr/share/wazuh-indexer/opensearch-security/securityconfig/internal_users.yml +``` + +> **Note**: Ensure the file exists on your host before starting the containers to prevent Docker from creating it as a directory. + +#### Applying Changes + +After modifying `internal_users.yml`, restart the stack to apply the changes: + +```bash +docker-compose down +``` + +```bash +docker-compose up -d +``` + +## Other Components + +For other components like the Wazuh Manager and Wazuh Dashboard, persistence is typically handled by mounting their respective configuration directories or using Docker volumes for data storage. + +- **Wazuh Manager**: Persist `/var/ossec/data` and `/var/ossec/etc` (or specific files like `ossec.conf`) to retain rules, decoders, and logs. +- **Wazuh Dashboard**: Persist `/usr/share/wazuh-dashboard/data` to retain tenants, dashboards, and visualizations. + +Refer to the [Configuration Files](configuration-files.md) section for more details on mapping specific configuration files. diff --git a/docs/ref/upgrade.md b/docs/ref/upgrade.md index 1d455258..7e15c983 100644 --- a/docs/ref/upgrade.md +++ b/docs/ref/upgrade.md @@ -1,10 +1,79 @@ # Upgrading Wazuh in Docker -To upgrade your Wazuh deployment when using Docker, we recommend following the official Wazuh documentation. It contains the most accurate and up-to-date information for upgrading from previous versions to the current one. +To upgrade your Wazuh deployment when using Docker, the process primarily involves updating the image tags in your `docker-compose.yml` file to the desired version. -> 📘 Please refer to the official guide: -> [Upgrading Wazuh Docker](https://documentation.wazuh.com/current/deployment-options/docker/upgrading-wazuh-docker.html) +Below is a step-by-step example of how to perform this update: -This external guide provides detailed upgrade instructions that cover multiple scenarios and configurations. +1. **Stop the current deployment**: + Stop and remove the existing containers. + ```bash + docker-compose down + ``` -Following the official documentation ensures a smoother and safer upgrade process, with fewer risks of data loss or configuration issues. +2. **Update the image tags**: + Edit your `docker-compose.yml` file and update the `image` field for all Wazuh services to the desired version. + + ### Single-node configuration + Update the image tag for the following services in `single-node/docker-compose.yml`: + - `wazuh.manager` + - `wazuh.indexer` + - `wazuh.dashboard` + + Example (update to 5.0.0): + + ```yaml + services: + wazuh.manager: + image: wazuh/wazuh-manager:5.0.0 + ... + + wazuh.indexer: + image: wazuh/wazuh-indexer:5.0.0 + ... + + wazuh.dashboard: + image: wazuh/wazuh-dashboard:5.0.0 + ... + ``` + + ### Multi-node configuration + Update the image tag for the following services in `multi-node/docker-compose.yml`: + - `wazuh.master` + - `wazuh.worker` + - `wazuh1.indexer`, `wazuh2.indexer`, and `wazuh3.indexer` + - `wazuh.dashboard` + + Example (update to 5.0.0): + + ```yaml + services: + wazuh.master: + image: wazuh/wazuh-manager:5.0.0 + ... + + wazuh.worker: + image: wazuh/wazuh-manager:5.0.0 + ... + + wazuh1.indexer: + image: wazuh/wazuh-indexer:5.0.0 + ... + + wazuh2.indexer: + image: wazuh/wazuh-indexer:5.0.0 + ... + + wazuh3.indexer: + image: wazuh/wazuh-indexer:5.0.0 + ... + + wazuh.dashboard: + image: wazuh/wazuh-dashboard:5.0.0 + ... + ``` + +3. **Start the updated deployment**: + Start the containers again. Docker will automatically pull the new images. + ```bash + docker-compose up -d + ``` From cb4062c2b76a940fdf408beea7937456826a2daf Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Thu, 12 Feb 2026 14:54:11 -0500 Subject: [PATCH 4/6] Add specific links to tech docs --- docs/ref/backup-and-restore.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/ref/backup-and-restore.md b/docs/ref/backup-and-restore.md index d9179b67..ee512a68 100644 --- a/docs/ref/backup-and-restore.md +++ b/docs/ref/backup-and-restore.md @@ -2,5 +2,5 @@ For backup and restore, refer to the documentation for each component: -- [Wazuh central components](https://documentation.wazuh.com/current/migration-guide/index.html) -- [Wazuh agent](https://documentation.wazuh.com/current/migration-guide/index.html) +- [Wazuh manager](https://github.com/wazuh/wazuh/blob/v5.0.0/docs/ref/backup-restore.md) +- [Wazuh agent](https://github.com/wazuh/wazuh-agent/blob/v5.0.0/docs/ref/backup-restore.md) From b3d34a99839c5c22868f4b3a13f61ab3f420d1f7 Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Fri, 13 Feb 2026 12:38:16 -0500 Subject: [PATCH 5/6] Add general instructions for Docker volume persistence --- docs/ref/configuration/persistence.md | 33 +++++++++++++++++++++++++-- 1 file changed, 31 insertions(+), 2 deletions(-) diff --git a/docs/ref/configuration/persistence.md b/docs/ref/configuration/persistence.md index af8c9af9..183e29f4 100644 --- a/docs/ref/configuration/persistence.md +++ b/docs/ref/configuration/persistence.md @@ -2,6 +2,37 @@ 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. +## General Instructions + +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. + +### Using Docker Volumes for Persistence + +To persist files or directories in your Wazuh deployment, you can mount them as volumes in your `docker-compose.yml` file. The general syntax is: + +```yaml +services: + service_name: + volumes: + - /host/path/to/file:/container/path/to/file + - /host/path/to/directory:/container/path/to/directory +``` + +**Example**: To persist a specific configuration file: + +```yaml +services: + wazuh.indexer: + volumes: + - ./config/custom-config.yml:/usr/share/wazuh-indexer/config/custom-config.yml +``` + +> **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. + +For more information on Docker volumes and bind mounts, refer to the official Docker documentation: +- [Use volumes](https://docs.docker.com/storage/volumes/) +- [Bind mounts](https://docs.docker.com/storage/bind-mounts/) + ## Wazuh Indexer ### Internal Users @@ -53,8 +84,6 @@ services: - ./config/wazuh_indexer/internal_users.yml:/usr/share/wazuh-indexer/opensearch-security/securityconfig/internal_users.yml ``` -> **Note**: Ensure the file exists on your host before starting the containers to prevent Docker from creating it as a directory. - #### Applying Changes After modifying `internal_users.yml`, restart the stack to apply the changes: From 93975b3715cf8eff5a90268842acaa6ab6eccff5 Mon Sep 17 00:00:00 2001 From: Jesus Garcia Date: Fri, 13 Feb 2026 12:54:13 -0500 Subject: [PATCH 6/6] Move persistence configuration into configuration-files.md --- docs/SUMMARY.md | 1 - docs/ref/configuration/configuration-files.md | 17 ++- docs/ref/configuration/persistence.md | 106 ------------------ 3 files changed, 16 insertions(+), 108 deletions(-) delete mode 100644 docs/ref/configuration/persistence.md diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md index 5a09ca0a..28e0a483 100644 --- a/docs/SUMMARY.md +++ b/docs/SUMMARY.md @@ -24,7 +24,6 @@ - [Configuration](ref/configuration/configuration.md) - [Environment Variabless](ref/configuration/environment-variables.md) - [Configuration files](ref/configuration/configuration-files.md) - - [Persistence](ref/configuration/persistence.md) - [Upgrade](ref/upgrade.md) - [Uninstall](ref/uninstall.md) - [Backup and restore](ref/backup-and-restore.md) diff --git a/docs/ref/configuration/configuration-files.md b/docs/ref/configuration/configuration-files.md index 429a85f5..dbabf037 100644 --- a/docs/ref/configuration/configuration-files.md +++ b/docs/ref/configuration/configuration-files.md @@ -28,5 +28,20 @@ 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. + +For more information on Docker volumes and bind mounts, refer to the official Docker documentation: +- [Use volumes](https://docs.docker.com/storage/volumes/) +- [Bind mounts](https://docs.docker.com/storage/bind-mounts/) diff --git a/docs/ref/configuration/persistence.md b/docs/ref/configuration/persistence.md deleted file mode 100644 index 183e29f4..00000000 --- a/docs/ref/configuration/persistence.md +++ /dev/null @@ -1,106 +0,0 @@ -# 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. - -## General Instructions - -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. - -### Using Docker Volumes for Persistence - -To persist files or directories in your Wazuh deployment, you can mount them as volumes in your `docker-compose.yml` file. The general syntax is: - -```yaml -services: - service_name: - volumes: - - /host/path/to/file:/container/path/to/file - - /host/path/to/directory:/container/path/to/directory -``` - -**Example**: To persist a specific configuration file: - -```yaml -services: - wazuh.indexer: - volumes: - - ./config/custom-config.yml:/usr/share/wazuh-indexer/config/custom-config.yml -``` - -> **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. - -For more information on Docker volumes and bind mounts, refer to the official Docker documentation: -- [Use volumes](https://docs.docker.com/storage/volumes/) -- [Bind mounts](https://docs.docker.com/storage/bind-mounts/) - -## Wazuh Indexer - -### Internal Users - -The `internal_users.yml` file contains the initial users and passwords for the Wazuh Indexer. This file is not included by default in the repository and must be created manually if you wish to customize internal users or update passwords. - -#### Creating the Configuration File - -1. Create the directory: - ```bash - mkdir -p ./config/wazuh_indexer/ - ``` - -2. Create the file: Create `./config/wazuh_indexer/internal_users.yml` with your user definitions. Here is a basic example: - ```yaml - --- - # This is the internal user database - # The hash value is a bcrypt hash and can be generated with /usr/share/wazuh-indexer/plugins/opensearch-security/tools/hash.sh - - _meta: - type: "internalusers" - config_version: 2 - - # Default users - - admin: - hash: "$2a$12$VcCDgh2NDk07JGN0rjGbM.Ad41qVR/YFJcgHp0UGns5JDymv..TOG" - reserved: true - backend_roles: - - "admin" - description: "Admin user" - - kibanaserver: - hash: "$2a$12$4AcgAt3xwOWadA5s5blL6ev39OXDNhmOesEoo33eZtrq2N0YrU3H." - reserved: true - description: "Kibana server user" - ``` - -> **Important**: This example includes the default `admin` and `kibanaserver` users with their default passwords (hashed). These users are required for the standard `docker-compose.yml` configuration (e.g., `INDEXER_USERNAME=admin` and `DASHBOARD_USERNAME=kibanaserver`) to function correctly. If you change these passwords, you must also update the corresponding environment variables in your `docker-compose.yml`. - -#### Docker Compose Configuration - -To persist the `internal_users.yml` file, add a volume mount to your `docker-compose.yml` for the `wazuh.indexer` service: - -```yaml -services: - wazuh.indexer: - volumes: - - ./config/wazuh_indexer/internal_users.yml:/usr/share/wazuh-indexer/opensearch-security/securityconfig/internal_users.yml -``` - -#### Applying Changes - -After modifying `internal_users.yml`, restart the stack to apply the changes: - -```bash -docker-compose down -``` - -```bash -docker-compose up -d -``` - -## Other Components - -For other components like the Wazuh Manager and Wazuh Dashboard, persistence is typically handled by mounting their respective configuration directories or using Docker volumes for data storage. - -- **Wazuh Manager**: Persist `/var/ossec/data` and `/var/ossec/etc` (or specific files like `ossec.conf`) to retain rules, decoders, and logs. -- **Wazuh Dashboard**: Persist `/usr/share/wazuh-dashboard/data` to retain tenants, dashboards, and visualizations. - -Refer to the [Configuration Files](configuration-files.md) section for more details on mapping specific configuration files.