paulmataruso/wazuh-docker-orginal
1
0
Fork 0
mirror of https://github.com/wazuh/wazuh-docker.git synced 2025-10-31 03:53:32 +00:00
Code Issues Packages Projects Releases Wiki Activity

Add env vars, tests and upgrade doc

Browse Source
This commit is contained in:
vcerenu
2025-05-19 16:08:01 -03:00
parent ed4674215e
commit 6bc6569dc1
4 changed files with 182 additions and 232 deletions
Download Patch File Download Diff File Expand all files Collapse all files

257
README.md
View File

@@ -5,251 +5,50 @@
[![Documentation](https://img.shields.io/badge/docs-view-green.svg)](https://documentation.wazuh.com)
[![Documentation](https://img.shields.io/badge/web-view-green.svg)](https://wazuh.com)
In this repository you will find the containers to run:
## Description
* Wazuh manager: it runs the Wazuh manager, Wazuh API and Filebeat OSS
* Wazuh dashboard: provides a web user interface to browse through alert data and allows you to visualize the agents configuration and status.
* Wazuh indexer: Wazuh indexer container (working as a single-node cluster or as a multi-node cluster). **Be aware to increase the `vm.max_map_count` setting, as it's detailed in the [Wazuh documentation](https://documentation.wazuh.com/current/docker/wazuh-container.html#increase-max-map-count-on-your-host-linux).**
The `wazuh/wazuh-docker` repository provides resources to deploy the Wazuh cybersecurity platform using Docker containers. This setup enables easy installation and orchestration of the full Wazuh stack, including the Wazuh server, dashboard (based on OpenSearch Dashboards), and OpenSearch for indexing and search.
The folder `build-docker-images` contains a README explaining how to build the Wazuh images and the necessary assets.
The folder `indexer-certs-creator` contains a README explaining how to create the certificates creator tool and the necessary assets.
The folder `single-node` contains a README explaining how to run a Wazuh environment with one Wazuh manager, one Wazuh indexer, and one Wazuh dashboard.
The folder `multi-node` contains a README explaining how to run a Wazuh environment with two Wazuh managers, three Wazuh indexers, and one Wazuh dashboard.
## Capabilities
- Full deployment of the Wazuh stack using Docker.
- `docker compose` support for orchestration.
- Scalable architecture with multi-node support.
- Data persistence through configurable volumes.
- Ready-to-use configurations for production or testing environments.
## Branch Convention
- `main`: Developing and testing of new features.
- `X.Y.Z`: Version-specific branches (e.g., `4.12.2`, `4.11.0`, etc.).
## Documentation
* [Wazuh full documentation](http://documentation.wazuh.com)
* [Wazuh documentation for Docker](https://documentation.wazuh.com/current/docker/index.html)
* [Docker Hub](https://hub.docker.com/u/wazuh)
Official documentation is available at:
[https://documentation.wazuh.com/current/deployment-options/docker/index.html](https://documentation.wazuh.com/current/deployment-options/docker/index.html)
### Setup SSL certificate
You can also explore internal documentation in the [`docs`](https://github.com/wazuh/wazuh-docker/tree/main/docs) folder of this repository.
Before starting the environment it is required to provide an SSL certificate (or just generate one self-signed).
## Get Involved
Documentation on how to provide these two can be found at [Wazuh Docker Documentation](https://documentation.wazuh.com/current/docker/wazuh-container.html#production-deployment).
- **Fork the repository** and create your own branches to add features or fix bugs.
- **Open issues** to report bugs or request features.
- **Submit pull requests** following the contributing guidelines.
- Participate in [discussions](https://github.com/wazuh/wazuh-docker/discussions) if available.
## Environment Variables
Default values are included when available.
### Wazuh
```
API_USERNAME="wazuh-wui" # Wazuh API username
API_PASSWORD="MyS3cr37P450r.*-" # Wazuh API password - Must comply with requirements
# (8+ length, uppercase, lowercase, special chars)
INDEXER_URL=https://wazuh.indexer:9200 # Wazuh indexer URL
INDEXER_USERNAME=admin # Wazuh indexer Username
INDEXER_PASSWORD=SecretPassword # Wazuh indexer Password
FILEBEAT_SSL_VERIFICATION_MODE=full # Filebeat SSL Verification mode (full or none)
SSL_CERTIFICATE_AUTHORITIES="" # Path of Filebeat SSL CA
SSL_CERTIFICATE="" # Path of Filebeat SSL Certificate
SSL_KEY="" # Path of Filebeat SSL Key
```
### Dashboard
```
PATTERN="wazuh-alerts-*" # Default index pattern to use
CHECKS_PATTERN=true # Defines which checks must be considered by the healthcheck
CHECKS_TEMPLATE=true # step once the Wazuh app starts. Values must be true or false
CHECKS_API=true
CHECKS_SETUP=true
APP_TIMEOUT=20000 # Defines maximum timeout to be used on the Wazuh app requests
API_SELECTOR=true Defines if the user is allowed to change the selected API directly from the Wazuh app top menu
IP_SELECTOR=true # Defines if the user is allowed to change the selected index pattern directly from the Wazuh app top menu
IP_IGNORE="[]" # List of index patterns to be ignored
DASHBOARD_USERNAME=kibanaserver # Custom user saved in the dashboard keystore
DASHBOARD_PASSWORD=kibanaserver # Custom password saved in the dashboard keystore
WAZUH_MONITORING_ENABLED=true # Custom settings to enable/disable wazuh-monitoring indices
WAZUH_MONITORING_FREQUENCY=900 # Custom setting to set the frequency for wazuh-monitoring indices cron task
WAZUH_MONITORING_SHARDS=2 # Configure wazuh-monitoring-* indices shards and replicas
WAZUH_MONITORING_REPLICAS=0 ##
```
## Directory structure
├── build-docker-images
│   ├── build-images.sh
│   ├── build-images.yml
│   ├── README.md
│   ├── wazuh-agent
│   │   ├── config
│   │   │   ├── check_repository.sh
│   │   │   └── etc
│   │   │   ├── cont-init.d
│   │   │   │   ├── 0-wazuh-init
│   │   │   │   └── 1-agent
│   │   │   └── services.d
│   │   │   └── ossec-logs
│   │   │   └── run
│   │   └── Dockerfile
│   ├── wazuh-dashboard
│   │   ├── config
│   │   │   ├── check_repository.sh
│   │   │   ├── config.sh
│   │   │   ├── config.yml
│   │   │   ├── entrypoint.sh
│   │   │   ├── wazuh_app_config.sh
│   │   │   └── wazuh.yml
│   │   └── Dockerfile
│   ├── wazuh-indexer
│   │   ├── config
│   │   │   ├── action_groups.yml
│   │   │   ├── check_repository.sh
│   │   │   ├── config.sh
│   │   │   ├── config.yml
│   │   │   ├── entrypoint.sh
│   │   │   ├── internal_users.yml
│   │   │   ├── opensearch.yml
│   │   │   ├── roles_mapping.yml
│   │   │   ├── roles.yml
│   │   │   └── securityadmin.sh
│   │   └── Dockerfile
│   └── wazuh-manager
│   ├── config
│   │   ├── check_repository.sh
│   │   ├── create_user.py
│   │   ├── etc
│   │   │   ├── cont-init.d
│   │   │   │   ├── 0-wazuh-init
│   │   │   │   ├── 1-config-filebeat
│   │   │   │   └── 2-manager
│   │   │   └── services.d
│   │   │   ├── filebeat
│   │   │   │   ├── finish
│   │   │   │   └── run
│   │   │   └── ossec-logs
│   │   │   └── run
│   │   ├── filebeat_module.sh
│   │   ├── filebeat.yml
│   │   ├── permanent_data.env
│   │   └── permanent_data.sh
│   └── Dockerfile
├── CHANGELOG.md
├── docs
│   ├── book.toml
│   ├── build.sh
│   ├── dev
│   │   ├── build-image.md
│   │   ├── README.md
│   │   ├── run-tests.md
│   │   └── setup.md
│   ├── README.md
│   ├── ref
│   │   ├── configuration
│   │   │   ├── configuration-files.md
│   │   │   ├── environment-variables.md
│   │   │   └── README.md
│   │   ├── getting-started
│   │   │   ├── deployment
│   │   │   │   ├── multi-node.md
│   │   │   │   ├── README.md
│   │   │   │   ├── single-node.md
│   │   │   │   └── wazuh-agent.md
│   │   │   ├── README.md
│   │   │   └── requirements.md
│   │   ├── glossary.md
│   │   ├── Introduction
│   │   │   ├── compatibility.md
│   │   │   ├── description.md
│   │   │   └── README.md
│   │   ├── README.md
│   │   └── upgrade.md
│   ├── server.sh
│   └── SUMMARY.md
├── indexer-certs-creator
│   ├── config
│   │   └── entrypoint.sh
│   ├── Dockerfile
│   └── README.md
├── LICENSE
├── multi-node
│   ├── config
│   │   ├── certs.yml
│   │   ├── nginx
│   │   │   └── nginx.conf
│   │   ├── wazuh_cluster
│   │   │   ├── wazuh_manager.conf
│   │   │   └── wazuh_worker.conf
│   │   ├── wazuh_dashboard
│   │   │   ├── opensearch_dashboards.yml
│   │   │   └── wazuh.yml
│   │   └── wazuh_indexer
│   │   ├── internal_users.yml
│   │   ├── wazuh1.indexer.yml
│   │   ├── wazuh2.indexer.yml
│   │   └── wazuh3.indexer.yml
│   ├── docker-compose.yml
│   ├── generate-indexer-certs.yml
│   ├── Migration-to-Wazuh-4.4.md
│   ├── README.md
│   └── volume-migrator.sh
├── README.md
├── SECURITY.md
├── single-node
│   ├── config
│   │   ├── certs.yml
│   │   ├── wazuh_cluster
│   │   │   └── wazuh_manager.conf
│   │   ├── wazuh_dashboard
│   │   │   ├── opensearch_dashboards.yml
│   │   │   └── wazuh.yml
│   │   ├── wazuh_indexer
│   │   │   ├── internal_users.yml
│   │   │   └── wazuh.indexer.yml
│   │   └── wazuh_indexer_ssl_certs [error opening dir]
│   ├── docker-compose.yml
│   ├── generate-indexer-certs.yml
│   └── README.md
├── VERSION.json
└── wazuh-agent
├── config
│   └── wazuh-agent-conf
└── docker-compose.yml
## Branches
* `main` branch contains the latest code, be aware of possible bugs on this branch.
## Compatibility Matrix
| Wazuh version | ODFE | XPACK |
|---------------|---------|--------|
| v4.3.0+ | | |
| v4.2.7 | 1.13.2 | 7.11.2 |
| v4.2.6 | 1.13.2 | 7.11.2 |
| v4.2.5 | 1.13.2 | 7.11.2 |
| v4.2.4 | 1.13.2 | 7.11.2 |
| v4.2.3 | 1.13.2 | 7.11.2 |
| v4.2.2 | 1.13.2 | 7.11.2 |
| v4.2.1 | 1.13.2 | 7.11.2 |
| v4.2.0 | 1.13.2 | 7.10.2 |
| v4.1.5 | 1.13.2 | 7.10.2 |
| v4.1.4 | 1.12.0 | 7.10.2 |
| v4.1.3 | 1.12.0 | 7.10.2 |
| v4.1.2 | 1.12.0 | 7.10.2 |
| v4.1.1 | 1.12.0 | 7.10.2 |
| v4.1.0 | 1.12.0 | 7.10.2 |
| v4.0.4 | 1.11.0 | |
| v4.0.3 | 1.11.0 | |
| v4.0.2 | 1.11.0 | |
| v4.0.1 | 1.11.0 | |
| v4.0.0 | 1.10.1 | |
## Credits and Thank you
## Authors / Maintainers
These Docker containers are based on:
* "deviantony" dockerfiles which can be found at [https://github.com/deviantony/docker-elk](https://github.com/deviantony/docker-elk)
* "xetus-oss" dockerfiles, which can be found at [https://github.com/xetus-oss/docker-ossec-server](https://github.com/xetus-oss/docker-ossec-server)
This project is maintained by the [Wazuh](https://wazuh.com) team, with active contributions from the community.
See the full list of contributors at:
[https://github.com/wazuh/wazuh-docker/graphs/contributors](https://github.com/wazuh/wazuh-docker/graphs/contributors)
We thank them and everyone else who has contributed to this project.
## License and copyright

29
docs/dev/run-tests.md
View File

@@ -1 +1,28 @@
# Run Tests
# Pull Request Test Execution
This repository includes automated tests designed to validate the correct deployment of Wazuh using Docker. These tests are executed on every pull request (PR) to ensure the integrity and stability of the system when changes are introduced.
## Purpose
The main objective of the tests is to verify that the Wazuh Docker environment can be successfully deployed and that all its core components (Wazuh Manager, Indexer, Dashboard, and Agents) operate as expected after any modification in the codebase.
## When Tests Run
- Tests are automatically triggered on every pull request (PR) opened against the repository.
- They also run when changes are pushed to an existing PR.
## What Is Tested
The tests aim to ensure:
- Successful build and startup of all Docker containers.
- Proper communication between components (e.g., Manager ↔ Indexer, Dashboard ↔ API).
- No critical errors appear in the logs.
- Key services are healthy and accessible.
## Benefits
- Reduces the risk of breaking the deployment flow.
- Ensures system consistency during feature development and refactoring.
- Provides early feedback on integration issues before merging.
---

117
docs/ref/configuration/environment-variables.md
View File

@@ -1 +1,116 @@
# Environment Variabless
# Environment Variables in Wazuh Docker Deployment
This document outlines the environment variables applicable to the Wazuh Docker deployment, covering the Wazuh Manager, Indexer, Dashboard, and Agent components. It also explains how to override configuration settings using environment variables.
## Table of Contents
- [Wazuh Manager](#wazuh-manager)
- [Wazuh Indexer](#wazuh-indexer)
- [Wazuh Dashboard](#wazuh-dashboard)
- [Wazuh Agent](#wazuh-agent)
- [Overriding Configuration Files with Environment Variables](#overriding-configuration-files-with-environment-variables)
---
## Wazuh Manager
The Wazuh Manager container accepts the following environment variables, which can be set in the `docker-compose.yml` file under the `environment` section:
```yaml
environment:
- INDEXER_USERNAME=admin
- INDEXER_PASSWORD=SecretPassword
- WAZUH_API_URL=https://wazuh.manager
- DASHBOARD_USERNAME=kibanaserver
- DASHBOARD_PASSWORD=kibanaserver
- API_USERNAME=wazuh-wui
- API_PASSWORD=MyS3cr37P450r.*-
```
**Variable Descriptions:**
- `INDEXER_USERNAME` / `INDEXER_PASSWORD`: Credentials for accessing the Wazuh Indexer with `admin` user or a user with the same permissions.
- `WAZUH_API_URL`: URL of the Wazuh API, used by other services for communication.
- `DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD`: Credentials for the Wazuh Dashboard to authenticate with the Indexer.
- `API_USERNAME` / `API_PASSWORD`: Credentials for the Wazuh API user, utilized by the Dashboard for API interactions.
---
## Wazuh Indexer
The Wazuh Indexer services (`single-node` and `multi-node`) use the following environment variable:
```yaml
environment:
- "OPENSEARCH_JAVA_OPTS=-Xms1g -Xmx1g"
```
**Variable Descriptions:**
- `OPENSEARCH_JAVA_OPTS`: Sets JVM heap size and other Java options.
---
## Wazuh Dashboard
The Wazuh Dashboard container accepts the following environment variables, which should be set in the `docker-compose.yml` file:
```yaml
environment:
- INDEXER_USERNAME=admin
- INDEXER_PASSWORD=SecretPassword
- WAZUH_API_URL=https://wazuh.manager
- DASHBOARD_USERNAME=kibanaserver
- DASHBOARD_PASSWORD=kibanaserver
- API_USERNAME=wazuh-wui
- API_PASSWORD=MyS3cr37P450r.*-
```
**Variable Descriptions:**
- `INDEXER_USERNAME` / `INDEXER_PASSWORD`: Credentials used by the Dashboard to authenticate with the Wazuh Indexer.
- `WAZUH_API_URL`: Base URL of the Wazuh API, used for querying and visualizing security data.
- `DASHBOARD_USERNAME` / `DASHBOARD_PASSWORD`: User credentials for the Dashboard interface.
- `API_USERNAME` / `API_PASSWORD`: API user credentials for authenticating Wazuh API requests initiated by the Dashboard.
These variables are critical for enabling communication between the Wazuh Dashboard, the Wazuh Indexer, and the Wazuh API.
---
## Wazuh Agent
The Wazuh Agent container uses the following environment variables to dynamically update the `ossec.conf` configuration file at runtime:
```yaml
environment:
- WAZUH_MANAGER_SERVER=wazuh.manager
- WAZUH_MANAGER_PORT=1514
- WAZUH_REGISTRATION_SERVER=wazuh.manager
- WAZUH_REGISTRATION_PORT=1515
- WAZUH_AGENT_NAME=my-agent
- WAZUH_REGISTRATION_PASSWORD=StrongPassword
```
These variables are used by the `set_manager_conn()` function in the entrypoint script to replace placeholder values in `ossec.conf` and set the enrollment password.
---
## Overriding Configuration Files with Environment Variables
To override configuration values from files such as `opensearch.yml` and `opensearch_dashboards.yml` using environment variables:
1. Convert the configuration key to uppercase.
2. Replace any dots (`.`) in the key with underscores (`_`).
3. Assign the corresponding value.
### Examples:
| YAML Key | Environment Variable |
|-----------------------------------------|--------------------------------------------|
| `discovery.type: single-node` | `DISCOVERY_TYPE=single-node` |
| `opensearch.hosts: https://url:9200` | `OPENSEARCH_HOSTS=https://url:9200` |
| `server.port: 5601` | `SERVER_PORT=5601` |
This approach allows you to configure the services dynamically via Docker without modifying internal files.
---

11
docs/ref/upgrade.md
View File

@@ -1 +1,10 @@
# Upgrade
# 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.
> 📘 Please refer to the official guide:
> [Upgrading Wazuh Docker](https://documentation.wazuh.com/current/deployment-options/docker/upgrading-wazuh-docker.html)
This external guide provides detailed upgrade instructions that cover multiple scenarios and configurations.
Following the official documentation ensures a smoother and safer upgrade process, with fewer risks of data loss or configuration issues.