# Upgrading Wazuh 4.14 - Step-by-Step Procedure

> Wazuh upgrade procedure to version 4.14 covering component upgrade order, compatibility matrix, rollback strategy, and troubleshooting

Source: https://opennix.org/en/docs/wazuh/operations/wazuh-upgrade/


Upgrading Wazuh requires updating all central components and agents in a strictly defined sequence. Version mismatches between components cause platform instability. This guide details every stage of upgrading to version 4.14, including preparation, step-by-step instructions, post-upgrade verification, and rollback procedures.

## Version Compatibility Matrix

All Wazuh central components must share the same version number, including the patch level. Mismatched versions lead to inter-component communication failures.

| Component | Version Requirement | Dependencies |
|---|---|---|
| Wazuh Indexer | Must match Server and Dashboard | Filebeat-OSS 7.10.2 |
| Wazuh Server | Must match Indexer and Dashboard | Filebeat-OSS 7.10.2 |
| Wazuh Dashboard | Must match Indexer and Server | - |
| Wazuh Agent | Manager version >= agent version | - |

### Agent Version Compatibility

The Wazuh Agent is compatible with a Wazuh Server of the same or newer version. A server running 4.14 can manage agents on version 4.9 and later. The reverse scenario (an agent newer than the server) is not supported.

## Upgrade Order

Components must be upgraded in the following order:

1. **Wazuh Indexer** - the data store is upgraded first
2. **Wazuh Server** (manager + Filebeat) - the event processing engine
3. **Wazuh Dashboard** - the web interface
4. **Wazuh Agent** - endpoint agents (after all central components)

Deviating from this order may result in data loss or platform downtime.

## Pre-Upgrade Preparation

### Pre-upgrade Checklist

Complete the following checks before starting the upgrade:

- [ ] Created a [backup](/docs/wazuh/operations/wazuh-backup/) of all component configurations and data
- [ ] Recorded current versions of all components
- [ ] Verified Wazuh repository accessibility or prepared packages for offline installation
- [ ] Scheduled a maintenance window (central component upgrades require service downtime)
- [ ] Exported Dashboard custom objects (visualizations, dashboards, saved searches)
- [ ] Verified indexer cluster health (all nodes reporting `green` status)
- [ ] Noted ML Commons model and agent IDs (if using AI integrations)

### Checking Current Versions

```bash
# Package versions (RPM)
rpm -qa | grep wazuh

# Package versions (DEB)
dpkg -l | grep wazuh

# Manager version via API
curl -sk -u wazuh-wui:<PASSWORD> \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true" \
  | xargs -I {} curl -sk -H "Authorization: Bearer {}" \
  "https://localhost:55000/manager/info" | jq '.data.affected_items[0].version'

# Indexer cluster health
curl -sk -u admin:<PASSWORD> \
  "https://localhost:9200/_cluster/health?pretty"
```

### Exporting Dashboard Objects

Before upgrading the Dashboard, preserve custom objects:

1. Open the Wazuh Dashboard
2. Navigate to **Stack Management** > **Saved Objects**
3. Select all objects and click **Export**
4. Store the exported file in a safe location

### Enabling the Wazuh Repository

The upgrade requires access to the Wazuh package repository. If it was disabled after the initial installation, re-enable it:

**RPM-based distributions (CentOS, RHEL, Amazon Linux):**

```bash
sed -i "s/^enabled=0/enabled=1/" /etc/yum.repos.d/wazuh.repo
```

**DEB-based distributions (Ubuntu, Debian):**

```bash
sed -i "s/^#deb /deb /" /etc/apt/sources.list.d/wazuh.list
apt-get update
```

## Upgrading the Wazuh Indexer

The Wazuh Indexer is upgraded first. In a multi-node cluster, nodes are upgraded one at a time, with the `cluster_manager` node upgraded last.

### Preparing the Cluster

1. Back up the security configuration:

```bash
/usr/share/wazuh-indexer/bin/indexer-security-init.sh \
  --options "-backup /etc/wazuh-indexer/opensearch-security -icl -nhnv"
```

2. Disable shard reallocation to prevent unnecessary load during the upgrade:

```bash
curl -sk -u admin:<PASSWORD> \
  -X PUT "https://localhost:9200/_cluster/settings" \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "primaries"
    }
  }'
```

3. Flush the translog:

```bash
curl -sk -u admin:<PASSWORD> \
  -X POST "https://localhost:9200/_flush"
```

4. Stop Filebeat and Dashboard:

```bash
systemctl stop filebeat
systemctl stop wazuh-dashboard
```

### Upgrading an Indexer Node

Perform the following steps on each node (one at a time in a multi-node cluster):

1. Stop the indexer service:

```bash
systemctl stop wazuh-indexer
```

2. Save the current JVM settings:

```bash
cp /etc/wazuh-indexer/jvm.options /etc/wazuh-indexer/jvm.options.bak
```

3. Upgrade the package:

```bash
# RPM
yum upgrade wazuh-indexer

# DEB
apt-get install wazuh-indexer
```

4. Restore custom JVM settings (heap size and other tuning parameters):

```bash
# Compare files and reapply custom settings
diff /etc/wazuh-indexer/jvm.options /etc/wazuh-indexer/jvm.options.bak
```

5. Restart the service:

```bash
systemctl daemon-reload
systemctl enable wazuh-indexer
systemctl start wazuh-indexer
```

6. Wait for the node to rejoin the cluster (30-60 seconds) and verify its status:

```bash
curl -sk -u admin:<PASSWORD> \
  "https://localhost:9200/_cat/nodes?v"
```

### Completing the Indexer Upgrade

After all nodes have been upgraded:

1. Restore the security configuration:

```bash
/usr/share/wazuh-indexer/bin/indexer-security-init.sh
```

2. Re-enable shard allocation:

```bash
curl -sk -u admin:<PASSWORD> \
  -X PUT "https://localhost:9200/_cluster/settings" \
  -H "Content-Type: application/json" \
  -d '{
    "persistent": {
      "cluster.routing.allocation.enable": "all"
    }
  }'
```

3. Verify cluster health:

```bash
curl -sk -u admin:<PASSWORD> \
  "https://localhost:9200/_cluster/health?pretty"
```

The cluster should return to `green` status. A `yellow` status indicates shard reallocation is still in progress.

## Upgrading the Wazuh Server

The Wazuh Server is upgraded after the indexer. In a cluster configuration, upgrade worker nodes first, then the master node.

### Upgrading the Manager

1. Upgrade the package:

```bash
# RPM
yum upgrade wazuh-manager

# DEB
apt-get install wazuh-manager
```

A modified `/var/ossec/etc/ossec.conf` is not overwritten during the upgrade. New configuration parameters must be added manually.

2. Start the service:

```bash
systemctl daemon-reload
systemctl enable wazuh-manager
systemctl start wazuh-manager
```

3. Verify the status:

```bash
systemctl status wazuh-manager
```

### Additional Configuration for Upgrades from Earlier Versions

**When upgrading from version 4.12.x or earlier**, add the CDB lists for IoC detection to `/var/ossec/etc/ossec.conf`:

```xml
<ruleset>
  <list>etc/lists/audit-keys</list>
  <list>etc/lists/amazon/aws-eventnames</list>
  <list>etc/lists/security-eventchannel</list>
  <list>etc/lists/malicious-ioc-md5</list>
  <list>etc/lists/malicious-ioc-sha1</list>
  <list>etc/lists/malicious-ioc-sha256</list>
</ruleset>
```

**When upgrading from version 4.7.x or earlier**, configure the vulnerability detection module and indexer connector:

```xml
<vulnerability-detection>
  <enabled>yes</enabled>
  <index-status>yes</index-status>
  <feed-update-interval>60m</feed-update-interval>
</vulnerability-detection>

<indexer>
  <enabled>yes</enabled>
  <hosts>
    <host>https://INDEXER_IP:9200</host>
  </hosts>
</indexer>
```

Store credentials in the keystore:

```bash
echo '<USERNAME>' | /var/ossec/bin/wazuh-keystore -f indexer -k username
echo '<PASSWORD>' | /var/ossec/bin/wazuh-keystore -f indexer -k password
systemctl restart wazuh-manager
```

### Upgrading Filebeat

1. Download the updated Wazuh module for Filebeat:

```bash
curl -s https://packages.wazuh.com/4.x/filebeat/wazuh-filebeat-0.5.tar.gz \
  | tar -xvz -C /usr/share/filebeat/module
```

2. Download the updated index template:

```bash
curl -so /etc/filebeat/wazuh-template.json \
  https://raw.githubusercontent.com/wazuh/wazuh/v4.14.4/extensions/elasticsearch/7.x/wazuh-template.json
```

3. Upgrade the Filebeat package:

```bash
# RPM
yum upgrade filebeat

# DEB
apt-get install filebeat
```

4. Restart Filebeat and apply the configuration:

```bash
systemctl daemon-reload
systemctl enable filebeat
systemctl start filebeat

filebeat setup --pipelines
filebeat setup --index-management
```

5. Verify the Filebeat connection to the indexer:

```bash
filebeat test output
```

## Upgrading the Wazuh Dashboard

The Dashboard is upgraded after both the server and the indexer.

1. Back up the current configuration:

```bash
cp /etc/wazuh-dashboard/opensearch_dashboards.yml \
   /etc/wazuh-dashboard/opensearch_dashboards.yml.bak
```

2. Upgrade the package:

```bash
# RPM
yum upgrade wazuh-dashboard

# DEB
apt-get install wazuh-dashboard
```

3. Verify SSL certificate paths in the configuration:

```bash
grep -E "server.ssl.(key|certificate)" /etc/wazuh-dashboard/opensearch_dashboards.yml
```

Confirm that the certificate paths are correct and the files exist.

4. When upgrading from version 4.7 or earlier, add the default route:

```yaml
uiSettings.overrides.defaultRoute: /app/wz-home
```

5. Restart the Dashboard:

```bash
systemctl daemon-reload
systemctl enable wazuh-dashboard
systemctl start wazuh-dashboard
```

6. Import previously saved objects through **Stack Management** > **Saved Objects** > **Import**.

## Upgrading Wazuh Agents

Agents are upgraded after all central components. Wazuh supports two upgrade methods.

### Remote Upgrade

Remote upgrades are performed using the `agent_upgrade` utility or the API:

```bash
# Upgrade a specific agent
/var/ossec/bin/agent_upgrade -a 001

# Upgrade all agents
/var/ossec/bin/agent_upgrade -a all
```

Via the API:

```bash
TOKEN=$(curl -sk -u wazuh-wui:<PASSWORD> \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")

curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/upgrade?agents_list=001"
```

### Local Upgrade

**Linux (RPM):**

```bash
yum upgrade wazuh-agent
systemctl restart wazuh-agent
```

**Linux (DEB):**

```bash
apt-get install wazuh-agent
systemctl restart wazuh-agent
```

**Windows:**

Download the MSI installer from [packages.wazuh.com](https://packages.wazuh.com/4.x/windows/) and run the installation over the existing version. Agent configuration is preserved.

**macOS:**

```bash
curl -so wazuh-agent.pkg \
  https://packages.wazuh.com/4.x/macos/wazuh-agent-4.14.4-1.arm64.pkg
sudo installer -pkg wazuh-agent.pkg -target /
sudo /Library/Ossec/bin/wazuh-control restart
```

## Post-Upgrade Verification

After upgrading all components, run the following checks:

```bash
# Installed package versions
rpm -qa | grep wazuh   # or dpkg -l | grep wazuh

# Service status
systemctl status wazuh-indexer
systemctl status wazuh-manager
systemctl status filebeat
systemctl status wazuh-dashboard

# Indexer cluster health
curl -sk -u admin:<PASSWORD> \
  "https://localhost:9200/_cluster/health?pretty"

# Connected agents
TOKEN=$(curl -sk -u wazuh-wui:<PASSWORD> \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?status=active&limit=5" \
  | jq '.data.affected_items[] | {id, name, version, status}'
```

## Disabling Repositories After Upgrade

To prevent accidental upgrades, disable the repositories:

```bash
# RPM
sed -i "s/^enabled=1/enabled=0/" /etc/yum.repos.d/wazuh.repo

# DEB
sed -i "s/^deb /#deb /" /etc/apt/sources.list.d/wazuh.list
apt-get update
```

## Rollback on Upgrade Failure

Downgrading to version 4.11 or earlier is not possible due to changes in the Apache Lucene data format. To protect against data loss:

1. Create [index snapshots](/docs/wazuh/operations/wazuh-backup/) before upgrading
2. Maintain configuration backups for all components
3. If one component fails to upgrade, do not proceed with the next
4. Restore the failed component from the previous version package and its configuration backup

For rollback within the 4.12+ release line:

```bash
# Stop the service
systemctl stop wazuh-indexer  # or wazuh-manager, wazuh-dashboard

# Install the previous version
yum downgrade wazuh-indexer-4.13.4-1
# or
apt-get install wazuh-indexer=4.13.4-1

# Restore configuration from backup
cp /backup/jvm.options /etc/wazuh-indexer/jvm.options

# Start the service
systemctl start wazuh-indexer
```

## Troubleshooting Upgrade Issues

### Indexer Fails to Start After Upgrade

Check the logs:

```bash
journalctl -u wazuh-indexer -n 50
cat /var/log/wazuh-indexer/wazuh-indexer.log
```

Common causes:

- Incompatible JVM settings (restore from backup)
- Insufficient disk space for index migration
- Incorrect file permissions on data directories

### Filebeat Cannot Connect to the Indexer

```bash
filebeat test output
```

Verify that SSL certificates match the upgraded version and that configuration paths are correct.

### Dashboard Displays Errors After Upgrade

Clear the browser cache and restart the Dashboard:

```bash
systemctl restart wazuh-dashboard
```

If the error persists, verify the certificate paths in `/etc/wazuh-dashboard/opensearch_dashboards.yml`.

### Agents Do Not Connect After Server Upgrade

Confirm that the agent version does not exceed the server version. Check the manager log:

```bash
tail -f /var/ossec/logs/ossec.log | grep -i error
```

For detailed agent connectivity diagnostics, see the [troubleshooting](/docs/wazuh/operations/wazuh-troubleshooting/) section.

## Related Sections

- [Wazuh Backup](/docs/wazuh/operations/wazuh-backup/) - creating backups before upgrades
- [Troubleshooting](/docs/wazuh/operations/wazuh-troubleshooting/) - diagnosing common issues
- [Wazuh Installation](/docs/wazuh/installation/) - initial deployment