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 + ```