Wazuh central components
This section guides you through the upgrade process of the Wazuh indexer, the Wazuh server, and the Wazuh dashboard.
All-in-one deployments: Execute all commands and configuration actions on the same node since all components run on a single system.
Multi-node cluster deployments: Run commands and apply configurations on the respective node where the component being upgraded is located.
Preparing the upgrade
In case Wazuh is installed in a multi-node cluster configuration, repeat the following steps for every node.
Ensure you have added the Wazuh repository to every Wazuh indexer, server, and dashboard node before proceeding to perform the upgrade actions.
Import the GPG key.
# rpm --import https://packages.wazuh.com/key/GPG-KEY-WAZUH
Add the repository.
# echo -e '[wazuh]\ngpgcheck=1\ngpgkey=https://packages.wazuh.com/key/GPG-KEY-WAZUH\nenabled=1\nname=EL-$releasever - Wazuh\nbaseurl=https://packages.wazuh.com/4.x/yum/\nprotect=1' | tee /etc/yum.repos.d/wazuh.repo
Install the following packages if missing.
# apt-get install gnupg apt-transport-https
Install the GPG key.
# curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --no-default-keyring --keyring gnupg-ring:/usr/share/keyrings/wazuh.gpg --import && chmod 644 /usr/share/keyrings/wazuh.gpg
Add the repository.
# echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" | tee -a /etc/apt/sources.list.d/wazuh.list
Update the packages information.
# apt-get update
Stop the Filebeat and Wazuh dashboard services if installed in the node.
# systemctl stop filebeat # systemctl stop wazuh-dashboard
# service filebeat stop # service wazuh-dashboard stop
Upgrading the Wazuh indexer
The Wazuh indexer cluster remains operational throughout the upgrade. The rolling upgrade process allows nodes to be updated one at a time, ensuring continuous service availability and minimizing disruptions. The steps detailed in the following sections apply to both single-node and multi-node Wazuh indexer clusters.
Preparing the Wazuh indexer cluster for upgrade
Perform the following steps on any of the Wazuh indexer nodes replacing <WAZUH_INDEXER_IP_ADDRESS>
, <USERNAME>
, and <PASSWORD>
.
Disable shard replication to prevent shard replicas from being created while Wazuh indexer nodes are being taken offline for the upgrade.
curl -X PUT "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cluster/settings" \ -u <USERNAME>:<PASSWORD> -k -H "Content-Type: application/json" -d ' { "persistent": { "cluster.routing.allocation.enable": "primaries" } }'
{ "acknowledged" : true, "persistent" : { "cluster" : { "routing" : { "allocation" : { "enable" : "primaries" } } } }, "transient" : {} }
Perform a flush operation on the cluster to commit transaction log entries to the index.
# curl -X POST "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_flush" -u <USERNAME>:<PASSWORD> -k
{ "_shards" : { "total" : 19, "successful" : 19, "failed" : 0 } }
Run the following command on the Wazuh manager node(s) if running a single-node Wazuh indexer cluster.
# systemctl stop wazuh-manager
# service wazuh-manager stop
Upgrading the Wazuh indexer nodes
Perform the following steps on each Wazuh indexer node to upgrade them. Upgrade nodes with the cluster_manager
role last to maintain cluster connectivity among online nodes.
Note
You can check the role of Wazuh indexer nodes in the cluster using the following command:
# curl -k -u <USERNAME>:<PASSWORD> https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
Stop the Wazuh indexer service.
# systemctl stop wazuh-indexer
# service wazuh-indexer stop
Upgrade the Wazuh indexer to the latest version.
# yum upgrade wazuh-indexer
# apt-get install wazuh-indexer
Restart the Wazuh indexer service.
# systemctl daemon-reload # systemctl enable wazuh-indexer # systemctl start wazuh-indexer
Choose one option according to the operating system used.
RPM-based operating system:
# chkconfig --add wazuh-indexer # service wazuh-indexer start
Debian-based operating system:
# update-rc.d wazuh-indexer defaults 95 10 # service wazuh-indexer start
Repeat steps 1 to 3 above on all Wazuh indexer nodes before proceeding to the post-upgrade actions.
Post-upgrade actions
Perform the following steps on any of the Wazuh indexer nodes replacing <WAZUH_INDEXER_IP_ADDRESS>
, <USERNAME>
, and <PASSWORD>
.
Check that the newly upgraded Wazuh indexer nodes are in the cluster.
# curl -k -u <USERNAME>:<PASSWORD> https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
Re-enable shard allocation.
# curl -X PUT "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cluster/settings" \ -u <USERNAME>:<PASSWORD> -k -H "Content-Type: application/json" -d ' { "persistent": { "cluster.routing.allocation.enable": "all" } } '
{ "acknowledged" : true, "persistent" : { "cluster" : { "routing" : { "allocation" : { "enable" : "all" } } } }, "transient" : {} }
Check the status of the Wazuh indexer cluster again to see if the shard allocation has finished.
# curl -k -u <USERNAME>:<PASSWORD> https://<WAZUH_INDEXER_IP_ADDRESS>:9200/_cat/nodes?v
ip heap.percent ram.percent cpu load_1m load_5m load_15m node.role node.roles cluster_manager name 172.18.0.3 34 86 32 6.67 5.30 2.53 dimr cluster_manager,data,ingest,remote_cluster_client - wazuh2.indexer 172.18.0.4 21 86 32 6.67 5.30 2.53 dimr cluster_manager,data,ingest,remote_cluster_client * wazuh1.indexer 172.18.0.2 16 86 32 6.67 5.30 2.53 dimr cluster_manager,data,ingest,remote_cluster_client - wazuh3.indexer
Run the following command on the Wazuh manager node(s) to start the Wazuh manager service if you stopped it earlier.
# systemctl start wazuh-manager
# service wazuh-manager start
Note
Note that the upgrade process doesn't update plugins installed manually. Outdated plugins might cause the upgrade to fail.
Run the following command on each Wazuh indexer node to list installed plugins and identify those that require an update:
# /usr/share/wazuh-indexer/bin/opensearch-plugin list
In the output, plugins that require an update will be labeled as "outdated".
Remove the outdated plugins and reinstall the latest version replacing
<PLUGIN_NAME>
with the name of the plugin:# /usr/share/wazuh-indexer/bin/opensearch-plugin remove <PLUGIN_NAME> # /usr/share/wazuh-indexer/bin/opensearch-plugin install <PLUGIN_NAME>
Upgrading the Wazuh server
When upgrading a multi-node Wazuh manager cluster, run the upgrade in every node. Start with the master node to reduce server downtime. To successfully upgrade the Wazuh server, follow these steps in order:
Configure the vulnerability detection. (if required based on the version you are upgrading from).
Note
Upgrading from Wazuh 4.2.x or lower creates the wazuh
operating system user and group to replace ossec
. To avoid upgrade conflicts, make sure that the wazuh
user and group are not present in your operating system.
Upgrading the Wazuh manager
Upgrade the Wazuh manager to the latest version:
# yum upgrade wazuh-manager
# apt-get install wazuh-manager
Warning
If the /var/ossec/etc/ossec.conf
configuration file was modified, it will not be replaced by the upgrade. You will therefore have to add the settings of the new capabilities manually. More information can be found in the User manual.
Configuring vulnerability detection
If upgrading from version 4.8.x or later, skip the vulnerability detection configuration and proceed to Configuring Filebeat. No action is needed as the vulnerability detection block is already configured.
When upgrading from Wazuh version 4.7.x or earlier, follow these steps to configure the vulnerability detection block.
Update the configuration file
Edit the
/var/ossec/etc/ossec.conf
file to include the new<vulnerability-detection>
block. Remove the old<vulnerability-detector>
block if it exists.The updated configuration enables the Wazuh Vulnerability Detection module to index vulnerabilities and alerts, with the vulnerability feed refreshing every 60 minutes. Add the following block to the configuration file:
<vulnerability-detection> <enabled>yes</enabled> <index-status>yes</index-status> <feed-update-interval>60m</feed-update-interval> </vulnerability-detection>
Configure the indexer block
Ensure the
<indexer>
block contains the details of your Wazuh indexer host. During the upgrade, a default<indexer>
configuration is added under<ossec_conf>
if none exists in/var/ossec/etc/ossec.conf
. By default, the configuration includes one host with the IP address0.0.0.0
:<indexer> <enabled>yes</enabled> <hosts> <host>https://0.0.0.0:9200</host> </hosts> <ssl> <certificate_authorities> <ca>/etc/filebeat/certs/root-ca.pem</ca> </certificate_authorities> <certificate>/etc/filebeat/certs/filebeat.pem</certificate> <key>/etc/filebeat/certs/filebeat-key.pem</key> </ssl> </indexer>
Replace
0.0.0.0
with the IP address or hostname of your Wazuh indexer node. You can find this value in the Filebeat configuration file at/etc/filebeat/filebeat.yml
. Ensure that the<certificate>
and<key>
names match the files located in/etc/filebeat/certs/
.If using a Wazuh indexer cluster, add a
<host>
entry in the Wazuh manager/var/ossec/etc/ossec.conf
file for each node in the cluster. For example, for a two-node configuration:<hosts> <host>https://10.0.0.1:9200</host> <host>https://10.0.0.2:9200</host> </hosts>
The Wazuh server will prioritize reporting to the first indexer node in the list and switch to the next available node if it becomes unavailable.
Store Wazuh indexer credentials
Save the Wazuh indexer username and password into the Wazuh manager keystore using the Wazuh-keystore tool:
# echo '<INDEXER_USERNAME>' | /var/ossec/bin/wazuh-keystore -f indexer -k username # echo '<INDEXER_PASSWORD>' | /var/ossec/bin/wazuh-keystore -f indexer -k password
If you have forgotten your Wazuh indexer password, refer to the password management guide to reset it.
Configuring Filebeat
When upgrading Wazuh, you must also update the Wazuh Filebeat module and the alerts template to ensure compatibility with the latest Wazuh indexer version. Follow these steps to configure Filebeat properly:
Download the Wazuh module for Filebeat:
# curl -s https://packages.wazuh.com/4.x/filebeat/wazuh-filebeat-0.4.tar.gz | sudo tar -xvz -C /usr/share/filebeat/module
Download the alerts template:
# curl -so /etc/filebeat/wazuh-template.json https://raw.githubusercontent.com/wazuh/wazuh/v4.10.1/extensions/elasticsearch/7.x/wazuh-template.json # chmod go+r /etc/filebeat/wazuh-template.json
Restart Filebeat:
# systemctl daemon-reload # systemctl enable filebeat # systemctl start filebeat
Choose one option according to the OS used:
Debian based OS
# update-rc.d filebeat defaults 95 10 # service filebeat start
RPM based OS
# chkconfig --add filebeat # service filebeat start
Upload the new Wazuh template and pipelines for Filebeat:
# filebeat setup --pipelines # filebeat setup --index-management -E output.logstash.enabled=false
If you are upgrading from Wazuh versions v4.8.x or v4.9.x, manually update the
wazuh-states-vulnerabilities-*
mappings using the following command. Replace<WAZUH_INDEXER_IP_ADDRESS>
,<USERNAME>
, and<PASSWORD>
with the values applicable to your deployment.Skip this step if upgrading from other versions.
curl -X PUT "https://<WAZUH_INDEXER_IP_ADDRESS>:9200/wazuh-states-vulnerabilities-*/_mapping" \ -u <USERNAME>:<PASSWORD> -k -H "Content-Type: application/json" -d ' { "properties": { "vulnerability": { "properties": { "under_evaluation": { "type": "boolean" }, "scanner": { "properties": { "source": { "type": "keyword", "ignore_above": 1024 } } } } } } } '
Upgrading the Wazuh dashboard
Backup the /etc/wazuh-dashboard/opensearch_dashboards.yml
file to save your settings. For example, create a copy of the file using the following command:
# cp /etc/wazuh-dashboard/opensearch_dashboards.yml /etc/wazuh-dashboard/opensearch_dashboards.yml.old
Upgrade the Wazuh dashboard.
# yum upgrade wazuh-dashboard
# apt-get install wazuh-dashboard
Note
When prompted, choose to replace the
/etc/wazuh-dashboard/opensearch_dashboards.yml
file with the updated version.Manually reapply any configuration changes to the
/etc/wazuh-dashboard/opensearch_dashboards.yml
file. Ensure that the values ofserver.ssl.key
andserver.ssl.certificate
match the files located in/etc/wazuh-dashboard/certs/
.Ensure the value of
uiSettings.overrides.defaultRoute
in the/etc/wazuh-dashboard/opensearch_dashboards.yml
file is set to/app/wz-home
as shown below:uiSettings.overrides.defaultRoute: /app/wz-home
Restart the Wazuh dashboard:
# systemctl daemon-reload # systemctl enable wazuh-dashboard # systemctl start wazuh-dashboard
Choose one option according to your operating system:
RPM-based operating system:
# chkconfig --add wazuh-dashboard # service wazuh-dashboard start
Debian-based operating system:
# update-rc.d wazuh-dashboard defaults 95 10 # service wazuh-dashboard start
You can now access the Wazuh dashboard via: https://<DASHBOARD_IP_ADDRESS>/app/wz-home
.
Note
Note that the upgrade process doesn't update plugins installed manually. Outdated plugins might cause the upgrade to fail.
Run the following command on the Wazuh dashboard server to list installed plugins and identify those that require an update:
# sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list
In the output, plugins that require an update will be labeled as "outdated".
Remove the outdated plugins and reinstall the latest version replacing
<PLUGIN_NAME>
with the name of the plugin:# sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin remove <PLUGIN_NAME> # sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin install <PLUGIN_NAME>
Next steps
The Wazuh server, indexer, and dashboard are now successfully upgraded. You can verify the versions by running the following commands on the node(s) where the central components are installed:
# yum list installed wazuh-indexer
# yum list installed wazuh-manager
# yum list installed wazuh-dashboard
# apt list --installed wazuh-indexer
# apt list --installed wazuh-manager
# apt list --installed wazuh-dashboard
Next, upgrade the Wazuh agents by following the instructions in Upgrading the Wazuh agent.