Upgrading Wazuh 4.14 - Step-by-Step Procedure

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:

Wazuh Indexer - the data store is upgraded first
Wazuh Server (manager + Filebeat) - the event processing engine
Wazuh Dashboard - the web interface
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 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

# 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:

Open the Wazuh Dashboard
Navigate to Stack Management > Saved Objects
Select all objects and click Export
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):

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

DEB-based distributions (Ubuntu, Debian):

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

Back up the security configuration:

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

Disable shard reallocation to prevent unnecessary load during the upgrade:

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

Flush the translog:

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

Stop Filebeat and Dashboard:

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):

Stop the indexer service:

systemctl stop wazuh-indexer

Save the current JVM settings:

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

Upgrade the package:

# RPM
yum upgrade wazuh-indexer

# DEB
apt-get install wazuh-indexer

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

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

Restart the service:

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

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

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

Completing the Indexer Upgrade

After all nodes have been upgraded:

Restore the security configuration:

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

Re-enable shard allocation:

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

Verify cluster health:

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

Upgrade the package:

# 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.

Start the service:

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

Verify the status:

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:

<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:

<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:

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

Download the updated Wazuh module for Filebeat:

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

Download the updated index template:

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

Upgrade the Filebeat package:

# RPM
yum upgrade filebeat

# DEB
apt-get install filebeat

Restart Filebeat and apply the configuration:

systemctl daemon-reload
systemctl enable filebeat
systemctl start filebeat

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

Verify the Filebeat connection to the indexer:

filebeat test output

Upgrading the Wazuh Dashboard

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

Back up the current configuration:

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

Upgrade the package:

# RPM
yum upgrade wazuh-dashboard

# DEB
apt-get install wazuh-dashboard

Verify SSL certificate paths in the configuration:

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

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

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

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

Restart the Dashboard:

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

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:

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

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

Via the API:

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):

yum upgrade wazuh-agent
systemctl restart wazuh-agent

Linux (DEB):

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

Windows:

Download the MSI installer from packages.wazuh.com and run the installation over the existing version. Agent configuration is preserved.

macOS:

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:

# 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:

# 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:

Create index snapshots before upgrading
Maintain configuration backups for all components
If one component fails to upgrade, do not proceed with the next
Restore the failed component from the previous version package and its configuration backup

For rollback within the 4.12+ release line:

# 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:

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

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:

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:

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

For detailed agent connectivity diagnostics, see the troubleshooting section.

Related Sections

Wazuh Backup - creating backups before upgrades
Troubleshooting - diagnosing common issues
Wazuh Installation - initial deployment

Last updated on 8, April 2026

Wazuh 4.14 Troubleshooting - Diagnostic Guide