# wazuh-upgrade-backup-retention

Companion files for the lesson [Wazuh Upgrade, Backup and Index Retention](https://maheshtata.com/wazuh/wazuh-upgrade-backup-retention/).

Tested against the Wazuh 5.0 beta5 documentation (September 2026). Wazuh 5.0 is
still in beta, so treat every value as subject to change at GA.

| File | What it is | How to use it |
| --- | --- | --- |
| `findings-retention-policy.json` | ISM policy for `wazuh-findings-v5-*` with retention raised from the default 90d to 180d | Indexer Management > Index Management > State management policies |
| `backup-indexer-config.sh` | Indexer **configuration** backup, commands taken verbatim from the docs | run as root on every indexer node |
| `backup-manager-config.sh` | Manager configuration, `client.keys`, `authd.pass` and group shared config | run as root on the manager |

## Default retention, so you know what you are changing

| Data stream | Default retention |
| --- | --- |
| `wazuh-events-raw-v5` | 10 minutes |
| `wazuh-events-v5-*` | 1 hour |
| `wazuh-findings-v5-*` | 90 days |
| `wazuh-active-responses` | 3 days |

Data streams roll over at **20 GB primary shard size** or **200 million
documents**, whichever comes first.

`min_index_age` on the transition into the `delete` state is the retention
knob. Everything else in the policy is rollover sizing.

## Applying the policy

On the dashboard: Indexer Management > Index Management > State management
policies, open `stream-findings-policy`, and edit the `min_index_age`
condition. The JSON here is what that edit produces.

Caveats that bite:

- ISM runs its job every **5 minutes** by default, so conditions are evaluated
  on that cadence, not continuously. It does not run while the cluster state
  is red.
- An `ism_template` applies only to indices created **after** it. Changing a
  policy does not retroactively re-manage existing indices.
- The Setup module recreates or updates Wazuh-managed **index templates** on
  every indexer start, and the documentation warns that manual template edits
  can be overwritten. Edit the ISM policies, not the templates, and re-check
  your retention after every upgrade.

## Backup, in two halves

Configuration and data are separate procedures. Running only the first and
calling it a backup is the common failure.

1. **Configuration.** `backup-indexer-config.sh` and
   `backup-manager-config.sh`. Documented restore is for the **same version**
   only; in a multi-node deployment, restore the matching backup on each node.
2. **Data.** Register a snapshot repository (`path.repo` in
   `opensearch.yml`, directory owned by `wazuh-indexer:wazuh-indexer`, plus
   `plugins.security.check_snapshot_restore_write_privileges: true` and
   `plugins.security.enable_snapshot_restore_privilege: true`), restart the
   indexer, then create the repository and take snapshots from
   Index management > Snapshot Management.
3. **Detection content.** Not on the manager filesystem. Export rules,
   decoders, integrations and KVDBs through the indexer content manager API
   and keep them in version control.

`backup-manager-config.sh` carries a caveat worth repeating: the 5.0 beta
documentation has **no manager files-backup page**. The paths in that script
are the 5.0 manager paths documented elsewhere in the beta, assembled into a
backup. Re-check against the official procedure at GA.

## Agent upgrade quick reference

```bash
# List outdated agents
/var/wazuh-manager/bin/agent_upgrade -l

# Upgrade from the online repository
/var/wazuh-manager/bin/agent_upgrade -a 011

# Several at once
/var/wazuh-manager/bin/agent_upgrade -a 002 003

# From a WPK you downloaded (recommended location /var/wazuh-manager/tmp/)
/var/wazuh-manager/bin/agent_upgrade -a 002 -f /var/wazuh-manager/tmp/wazuh_agent_v5.0.0_linux_amd64.deb.wpk

# Verify on the endpoint
/var/ossec/bin/wazuh-control info
```

**Version path:** direct upgrades to 5.0.0 are not supported from agent
4.14.0 or earlier. The documented order is 4.14.0 or earlier, then 4.14.x,
then 5.0.0. Two hops, two change windows.

`-F` forces past version validation, including that rule. Use it to recover a
stuck upgrade, not to skip a hop.

## Not covered here

Upgrading from 4.x to 5.0 is not an upgrade at all. There is no in-place path
and the 5.0 beta has no central components upgrade guide. See the
[4.x to 5 migration runbook](https://maheshtata.com/wazuh/wazuh-4-to-5-migration/).