> ## Documentation Index
> Fetch the complete documentation index at: https://docs.controlplane.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Wazuh

> Wazuh is open-source endpoint security (XDR and SIEM) with a manager, indexer and dashboard. Agents on your hosts connect over a public TCP load balancer. One location, optional workers and a 3-node indexer. Deploys into an existing GVC; needs one dictionary credentials secret first.

## Overview

[Wazuh](https://wazuh.com) is an open-source security platform. Agents on your Linux, Windows and macOS hosts report to a Wazuh server, which detects intrusions and malware, watches file integrity, finds vulnerable packages and checks configuration against compliance benchmarks. Alerts are stored in the Wazuh indexer and explored in the Wazuh dashboard. This template deploys all three, with agents connecting from anywhere over a public TCP load balancer.

Agents are the only ingestion path: the template has no syslog listener. To collect syslog from network devices, run an agent on the host that receives it. For general log search, see the related [OpenSearch](https://docs.controlplane.com/template-catalog/templates/opensearch.md) template.

> [!NOTE]
>
> This template deploys into an existing [GVC](https://docs.controlplane.com/reference/gvc.md) that you already have. It does not create or manage a GVC. Install into a GVC with a single location: the template runs in one location.

### What Gets Created

| Resource | Name | Purpose | Optional |
| - | - | - | - |
| Workload | `RELEASE_NAME-wazuh-manager` | Wazuh server: agent events on TCP `1514`, enrollment on `1515`, server API on `55000` (stateful, 1 replica) | — |
| Workload | `RELEASE_NAME-wazuh-worker` | Extra Wazuh server nodes that take agent traffic (stateful) | `manager.workers.replicas: 1` or more |
| Workload | `RELEASE_NAME-wazuh-indexer` | Stores alerts and inventory (stateful, 1 or 3 or more nodes) | — |
| Workload | `RELEASE_NAME-wazuh-dashboard` | Web UI (standard) | — |
| Workload | `RELEASE_NAME-wazuh-demo-agent` | A real agent in the GVC that fills the dashboard right away | `demoAgent.enabled: true` |
| Volume Set | `RELEASE_NAME-wazuh-manager-data` | Agent keys, server state, alert logs, custom rules and vulnerability content | — |
| Volume Set | `RELEASE_NAME-wazuh-worker-data` | Volume per worker | `manager.workers.replicas: 1` or more |
| Volume Set | `RELEASE_NAME-wazuh-indexer-data` | Volume per indexer node | — |
| Volume Set | `RELEASE_NAME-wazuh-pki` | Shared volume that hands the TLS certificates from the manager to the indexer and dashboard | — |
| Secret | `RELEASE_NAME-wazuh-manager-config` | Server configuration; no credentials | — |
| Identity | `RELEASE_NAME-wazuh-identity` | Identity of every workload | — |
| Policy | `RELEASE_NAME-wazuh-policy` | `reveal` on exactly the configuration secret and your credentials secret | — |

The manager creates a private certificate authority and the TLS certificates on first start. The CA key stays on the manager's own volume.

## Prerequisites

**1. Create the credentials secret**

One dictionary secret with exactly six keys must exist before you install:

```bash theme={null}
cpln secret create-dictionary --name SECRET_NAME \
  --entry indexerAdminPassword="Wz1.$(openssl rand -hex 16)" \
  --entry dashboardServerPassword="Wz2.$(openssl rand -hex 16)" \
  --entry apiPassword="Wz3.$(openssl rand -hex 16)" \
  --entry enrollmentPassword="Wz4.$(openssl rand -hex 16)" \
  --entry clusterKey="$(openssl rand -hex 16)" \
  --entry dashboardCookieSecret="$(openssl rand -hex 24)"
```

| Key | What it is |
| - | - |
| `indexerAdminPassword` | The indexer `admin` user: your dashboard login (username `admin`) |
| `dashboardServerPassword` | The indexer user the dashboard server connects with |
| `apiPassword` | The Wazuh server API user `wazuh-wui` the dashboard calls the manager with |
| `enrollmentPassword` | The password agents present on port `1515` to enroll |
| `clusterKey` | Exactly 32 letters, digits or underscores, shared by the manager and workers |
| `dashboardCookieSecret` | 32 or more characters; encrypts dashboard sessions |

Passwords are 8 to 64 characters, start with a letter, use only `A-Z a-z 0-9 . * + ? -`, and contain at least one upper-case letter, lower-case letter, digit and symbol. The `Wz1.` prefixes above satisfy that. Read the values back with `cpln secret reveal SECRET_NAME -o yaml`.

Set `credentialsSecretName` to this name.

> [!WARNING]
>
> If the secret does not exist at install time, every workload waits and `cpln logs` shows nothing. The reason appears only in `status.versions[].message` of `cpln workload get-deployments RELEASE_NAME-wazuh-manager --gvc GVC_NAME -o yaml`.

## Installation

Install the chart with the credentials secret name:

```bash theme={null}
cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/wazuh \
  --version 1.0.0 --gvc GVC_NAME \
  --set credentialsSecretName=SECRET_NAME
```

> [card] [UI](https://docs.controlplane.com/template-catalog/install-manage/ui.md)
>
> Browse, install, and manage templates visually

> [card] [CLI](https://docs.controlplane.com/template-catalog/install-manage/cli.md)
>
> Manage templates from your terminal

> [card] [Terraform](https://docs.controlplane.com/template-catalog/install-manage/terraform.md)
>
> Declare templates in your Terraform configurations

> [card] [Pulumi](https://docs.controlplane.com/template-catalog/install-manage/pulumi.md)
>
> Declare templates in your Pulumi programs

## Configuration

The default is one node of each component. Set `indexer.replicas: 3`, `manager.workers.replicas: 2` and `dashboard.replicas: 2` for near-zero-downtime upgrades. Each component also takes an `image` and a `resources` block; keep all images on the same Wazuh version.

### Credentials

```yaml theme={null}
credentialsSecretName: my-wazuh-credentials
```

### Manager

```yaml theme={null}
manager:
  logRetentionDays: 30 # delete dated alert/archive log files older than this many days; 0 = keep forever
  extraConfig: "" # raw <ossec_config>…</ossec_config> blocks appended to ossec.conf (UI edits to ossec.conf are reset on restart)
  publicAccess:
    enabled: true # agents connect from anywhere: TCP 1514 (events) and 1515 (enrollment) on a direct load balancer
    allowedCidrs: # source ranges allowed to reach the public ports
      - 0.0.0.0/0
    api: false # also expose the Wazuh server API (HTTPS, container port 55000) on the same load balancer, as port 8443
  internalAccess:
    type: same-gvc # options: same-gvc, same-org, workload-list (this release's own workloads are always allowed)
    workloads: # only used when type is same-gvc or workload-list
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
  volumeset:
    capacity: 50 # initial capacity in GiB (minimum is 10); holds agent keys, state, logs and vulnerability content
    snapshots:
      schedule: "0 3 * * *" # daily (agent keys and the CA key live only here) at 3am UTC; at most hourly; "" turns scheduled snapshots off
      retentionDuration: 7d # how long each snapshot is kept
```

Narrow `allowedCidrs` to the networks your agents connect from. Edits to `ossec.conf` made in the dashboard are reset on the next restart; put lasting changes in `extraConfig`. Custom rules, decoders and CDB lists made in the dashboard are kept. The manager volume holds every agent key and the CA key, so keep its snapshots on.

### Workers

```yaml theme={null}
manager:
  workers:
    replicas: 0 # 0 = the master handles everything; 1+ adds worker nodes that take agent traffic (point agents at the worker endpoint)
    volumeset:
      capacity: 20 # initial capacity in GiB per worker (minimum is 10)
      snapshots:
        schedule: "0 3 * * *" # daily at 3am UTC; at most hourly; "" turns scheduled snapshots off
        retentionDuration: 7d # how long each snapshot is kept
```

Workers keep agents connected while the manager restarts. With workers on, point agents at the worker load balancer; workers pass enrollment on to the manager, and the server API stays on the manager.

### Indexer

```yaml theme={null}
indexer:
  replicas: 1 # 1, or an odd number ≥ 3 for a cluster that keeps serving with a node down (3x the cost)
  javaHeap: 2g # JVM heap; keep it at about half of resources.maxMemory
  volumeset:
    capacity: 50 # initial capacity in GiB per node (minimum is 10); ~50 GiB holds 90 days for ~25 agents
    snapshots:
      schedule: "0 3 * * *" # daily at 3am UTC; at most hourly; "" turns scheduled snapshots off
      retentionDuration: 7d # how long each snapshot is kept
  retentionDays: 90 # delete alert/archive indices older than this many days; 0 = keep forever
  internalAccess:
    workloads: [] # extra workloads allowed to query the indexer (this release's own workloads are always allowed)
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
```

Every volume set also takes an `autoscaling` block (`enabled`, `maxCapacity`, `minFreePercentage`, `scalingFactor`), off by default. Sizing is roughly 2 GiB per agent per 90 days.

### Dashboard

```yaml theme={null}
dashboard:
  replicas: 1 # 2+ keeps the UI up through restarts
  publicAccess:
    enabled: true # HTTPS UI on the auto *.cpln.app endpoint; false = reach it with `cpln port-forward`
  internalAccess:
    type: same-gvc # options: none, same-gvc, same-org, workload-list
    workloads:
      #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
```

### Demo Agent

```yaml theme={null}
demoAgent:
  enabled: false # a Wazuh agent in this GVC that enrolls and sends sample events; turn off once real agents connect
```

## Connecting

| What | Address | Credentials |
| - | - | - |
| Dashboard | `status.canonicalEndpoint` of `RELEASE_NAME-wazuh-dashboard` (public), or `http://localhost:5601` through port-forward | `admin` and `indexerAdminPassword` |
| Agents outside Control Plane | The manager's load balancer host on ports `1514` and `1515` (the worker's when workers are on) | `enrollmentPassword` |
| Agents inside the GVC | `RELEASE_NAME-wazuh-manager.GVC_NAME.cpln.local`, ports `1514` and `1515` | `enrollmentPassword` |
| Server API | `https://RELEASE_NAME-wazuh-manager.GVC_NAME.cpln.local:55000`, or the load balancer host on port `8443` with `manager.publicAccess.api: true` | `wazuh-wui` and `apiPassword` |
| Indexer | `https://RELEASE_NAME-wazuh-indexer.GVC_NAME.cpln.local:9200` (this release's workloads and `indexer.internalAccess.workloads` only) | `admin` and `indexerAdminPassword` |

Read the credentials with `cpln secret reveal SECRET_NAME -o yaml`. The dashboard's `status.canonicalEndpoint` and the load balancer host are in each workload's status:

```bash theme={null}
cpln workload get RELEASE_NAME-wazuh-dashboard --gvc GVC_NAME -o yaml
cpln workload get RELEASE_NAME-wazuh-manager --gvc GVC_NAME -o yaml
```

The manager's `status.loadBalancer` lists `tcp://RELEASE_NAME-wazuh-manager-xxxx.yyyy.cpln.app:1514` and `…:1515`. To open a private dashboard (`dashboard.publicAccess.enabled: false`), forward it and browse to `http://localhost:5601`:

```bash theme={null}
cpln port-forward RELEASE_NAME-wazuh-dashboard 5601:5601 --gvc GVC_NAME
```

### Enrolling an Agent

Install the agent on a host with the load balancer host name and the enrollment password, for example on Debian or Ubuntu after adding the Wazuh package repository:

```bash theme={null}
sudo WAZUH_MANAGER="RELEASE_NAME-wazuh-manager-xxxx.yyyy.cpln.app" \
  WAZUH_REGISTRATION_PASSWORD="YOUR_ENROLLMENT_PASSWORD" \
  apt-get install wazuh-agent
sudo systemctl enable --now wazuh-agent
```

The dashboard's **Deploy new agent** page builds the same command for every operating system, with the host already filled in. The agent then appears under **Endpoints**.

## Operations

### Scaling and Availability

For near-zero-downtime upgrades and failover, set `indexer.replicas: 3`, `manager.workers.replicas: 2` and `dashboard.replicas: 2`. With the single-node default, a restart of the manager or indexer pauses event processing; agents and the indexer shipper buffer and resend, so events are delayed, not lost. Grow indexer storage with `indexer.volumeset.autoscaling`. Scale the indexer up, never down: removing nodes can lose the data they hold.

### Changing a Password

The secret is the source of truth on every start. Edit the key, then force a redeployment of the indexer, then the manager (and workers), then the dashboard. A password changed only in the dashboard reverts on the next restart.

```bash theme={null}
cpln secret edit SECRET_NAME
cpln workload force-redeployment RELEASE_NAME-wazuh-indexer --gvc GVC_NAME
cpln workload force-redeployment RELEASE_NAME-wazuh-manager --gvc GVC_NAME
cpln workload force-redeployment RELEASE_NAME-wazuh-dashboard --gvc GVC_NAME
```

### Troubleshooting

> [accordion] Nothing starts and the logs are empty
>
> The credentials secret is missing or misnamed. Read the reason from `status.versions[].message`:
>
> ```bash theme={null}
> cpln workload get-deployments RELEASE_NAME-wazuh-manager --gvc GVC_NAME -o yaml
> ```
>
> Create the secret or correct `credentialsSecretName`; the workloads then start on their own.

> [accordion] A workload exits with INVALID followed by a key name
>
> That key's password breaks the rules (8 to 64 characters, starts with a letter, only `A-Z a-z 0-9 . * + ? -`, one of each kind). Find the key in the logs, fix its value in the secret and force a redeployment of the workload:
>
> ```bash theme={null}
> cpln logs '{gvc="GVC_NAME", workload="RELEASE_NAME-wazuh-manager"} |= "INVALID"' --limit 50 --since 10m
> ```

> [accordion] Vulnerability Detection is empty
>
> The manager downloads about 1.7 GB of vulnerability content after the first install, which takes two hours or more. If the page is still empty after that, restart the manager once (**Server management**, **Status**, **Restart**).

> [accordion] An agent shows as disconnected after the demo agent restarts
>
> The demo agent enrolls under a new name each time it restarts and can leave the old entry disconnected. Remove stale entries under **Endpoints**, and turn the demo agent off once your own agents connect.

## Important Notes

* **Agent ports are open to the whole GVC while the load balancer is on.** `manager.internalAccess` does not restrict ports `1514` and `1515` when `manager.publicAccess.enabled` is `true`; the enrollment password is the gate. It restricts them (and the API) once the load balancer is off.
* **`manager.internalAccess.type` cannot be `none`**: the dashboard needs the API.
* **Custom rules in `extraConfig`.** A `<ruleset>` block replaces the default one, so restate the default `decoder_dir`, `rule_dir` and `list` entries in it, or the default rules stop loading. Workers load rules synced from the master after a restart (`PUT /cluster/restart`).
* **Restarts can repeat alerts.** Agents resend events the manager had not acknowledged, so an alert can appear twice after a restart. The **Statistics** page returns errors for about an hour after a manager start.
* **Access changes take time.** After changing `manager.publicAccess.*` or `dashboard.publicAccess.enabled`, allow 30 seconds to about 10 minutes for the firewall and load balancer to apply.
* **Never replace the manager volume set.** It holds every agent key and the CA key. If it is ever replaced, restart the indexer and dashboard so they pick up the new CA, and enroll the agents again.
* **Uninstalling deletes every volume set,** with the stored alerts and every agent key; a final snapshot of each is kept for `retentionDuration`.
* **Disk.** The indexer's disk watermarks are off (as upstream ships it), so a full volume stops indexing. Keep the retention values set or turn on volume autoscaling.
* **Indexer node count** must be `1` or an odd number of `3` or more.

## External References

* [Wazuh documentation](https://documentation.wazuh.com/4.14/index.html)
* [Installing Wazuh agents](https://documentation.wazuh.com/4.14/installation-guide/wazuh-agent/index.html)
* [Wazuh server cluster](https://documentation.wazuh.com/4.14/user-manual/wazuh-server-cluster/index.html)
* [Wazuh Docker images](https://github.com/wazuh/wazuh-docker)
