# wazuh-cluster

Companion files for the lesson **Wazuh Cluster and Distributed Architecture**:
<https://maheshtata.com/wazuh/wazuh-cluster/>

Tested against: Wazuh 5.0 (beta5 documentation, Sep 2026), Ubuntu 24.04.
Not yet validated in a lab; treat every value as a starting point.

## Files

| File | What it is |
| --- | --- |
| `certs-config.yml` | Node inventory for `wazuh-certs-tool`: three indexer nodes, a manager master and worker, one dashboard. Drives every certificate in the deployment. |
| `cluster-master.xml` | Partial `<cluster>` block for the manager master node. |
| `cluster-worker.xml` | Partial `<cluster>` block for a manager worker node. |
| `indexer-connector.xml` | Partial `<indexer>` block listing all indexer nodes, for every manager. |
| `cluster-health.sh` | Read-only health snapshot of the manager cluster and the indexer cluster. |

All four XML files are **fragments**. Merge them into the existing
`/var/wazuh-manager/etc/wazuh-manager.conf` inside `<wazuh_config>`. Do not
replace the file: in Wazuh 5.0 an unknown element is a startup error.

## Order of operations

1. Write `certs-config.yml` with the final node names and addresses. Every
   indexer node's `name` has to match the `node.name` you will set in
   `/etc/wazuh-indexer/opensearch.yml` on that host.
2. Generate and distribute the certificates before installing anything:
   `bash ./wazuh-certs-tool-5.0.0-beta5.sh -A`, then tar `./wazuh-certificates/`
   and copy the archive to every node.
3. Install and start the indexer nodes, then run
   `/usr/share/wazuh-indexer/bin/indexer-security-init.sh` **once**, on any one
   node.
4. Install the managers. Put `cluster-master.xml` on the master and
   `cluster-worker.xml` on each worker, with the same `<key>` and a unique
   `<node_name>` per node.
5. Put `indexer-connector.xml` on every manager.
6. Verify with `./cluster-health.sh`.

## Things these files deliberately leave to you

- **The cluster key.** Generate it with `openssl rand -hex 16` and keep it out
  of source control and shell history. The placeholder in both XML files is not
  a usable key.
- **Replica count.** The shipped index templates default to zero replicas.
  On a multi-node indexer set `cluster.default_number_of_replicas` rather than
  editing Wazuh-managed templates, which can be overwritten on restart.
- **Load balancer configuration.** No vendor-specific config is included,
  because the beta documentation gives requirements rather than a worked
  example: TLS 1.3 to the backend, no PROXY protocol, no session affinity, no
  path rewriting, aligned body-size and timeout limits, and a `POST /stateful`
  request that is never split or partially retried.

## Two documented values to check on your own host

The beta documentation is inconsistent about both, and either one will stop
agents connecting:

- `<remote><https><bind_addr>`: the configuration reference gives a default of
  `127.0.0.1`; the GitHub migration guide states `0.0.0.0`.
- `<remote><https><global_prefix>`: the reference says freshly generated
  configurations ship `/wazuh-manager/`; the migration guide's load-balancer
  section says remoted serves its routes at the root.

Read the effective values off the manager before configuring the load balancer
health check.