Skip to main content
This guide provides detailed procedures for upgrading the Wazuh dashboard to newer versions, ensuring a smooth transition while preserving your customizations and data.

​
Preparing the Upgrade

​
Export Dashboard Customizations

It is recommended to export customizations from the Wazuh dashboard. This step helps to preserve visualizations, dashboards, and other saved objects in case there are any issues during the upgrade process.
  1. Navigate to Dashboard management > Dashboards Management > Saved objects on the Wazuh dashboard.
  2. Select which objects to export and click Export, or click Export all objects to export everything.

​
Stop the Wazuh Dashboard Service

Systemd: 
systemctl stop wazuh-dashboard
SysV init: 
service wazuh-dashboard stop

​
Upgrading the Wazuh Dashboard

​
Backup Configuration

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 Package

Yum (RHEL/CentOS): 
yum upgrade wazuh-dashboard-5.0.0-1
APT (Debian/Ubuntu): 
apt-get install wazuh-dashboard=5.0.0-1
When prompted, choose to replace the /etc/wazuh-dashboard/opensearch_dashboards.yml file with the updated version.

​
Reapply Configuration Changes

Manually reapply any configuration changes to the /etc/wazuh-dashboard/opensearch_dashboards.yml file. Ensure that the values of server.ssl.key and server.ssl.certificate match the files located in /etc/wazuh-dashboard/certs/.

​
Set Default Route

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 Dashboard

Systemd: 
systemctl daemon-reload
systemctl enable wazuh-dashboard
systemctl start wazuh-dashboard
SysV init: 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

​
Verify the Upgrade

You can now access the Wazuh dashboard via: https://<DASHBOARD_IP_ADDRESS>/app/wz-home.

​
Import Saved Customizations

Import the saved customizations exported while preparing the upgrade:
  1. Navigate to Dashboard management > Dashboard Management > Saved objects on the Wazuh dashboard.
  2. Click Import, add the ndjson file and click Import.

​
Check Dashboard Functionality

Verify that all dashboard features are working correctly:
  • Access the main dashboard page
  • Navigate through different modules
  • Check agent status and monitoring
  • Test search and filtering functionality
  • Verify custom dashboards and visualizations load correctly

​
Migrating from 4.x to 5.x

If you are moving from 4.x to 5.x, review the migration checklist in the Migration guide (4.x to 5.x) before applying the upgrade.
The migration from 4.x to 5.x includes significant breaking changes that require special attention:
  • Configuration file structure changes
  • Index pattern updates
  • Plugin architecture modifications
  • Deprecated feature removal
Refer to the Migration guide (4.x to 5.x) for detailed migration steps.

​
Managing Plugins

The upgrade process does not update plugins installed manually. Outdated plugins might cause the upgrade to fail.

​
List Installed Plugins

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

​
Update Outdated Plugins

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>

​
Upgrade Best Practices

​
Pre-Upgrade Checklist

  • Review release notes for breaking changes
  • Export all saved objects and customizations
  • Backup configuration files
  • Backup certificates
  • Document current settings
  • Test upgrade in a non-production environment first
  • Schedule upgrade during maintenance window
  • Notify users of planned downtime

​
Post-Upgrade Checklist

  • Verify dashboard service is running
  • Check logs for errors
  • Test API connectivity
  • Verify index patterns
  • Import saved objects
  • Test core functionality
  • Verify agent connections
  • Check custom integrations
  • Validate user access and permissions
  • Monitor performance metrics

​
Version-Specific Notes

​
Wazuh 5.0.0

Key Changes:
  • Support for OpenSearch Dashboards 3.5.0
  • Default index pattern changed to wazuh-events*
  • Migration of settings from wazuh.yml to opensearch_dashboards.yml
  • Reworked health check functionality
  • New modular plugin architecture
Breaking Changes:
  • Removed wazuh-alerts* index pattern
  • Removed legacy App Settings application
  • Removed deprecated monitoring and statistics jobs
  • Removed Rules, Decoders, CDB List, and Ruleset test apps
  • Removed legacy reporting application

​
Wazuh 4.14.x

Key Changes:
  • Support for OpenSearch Dashboards 2.19.x
  • Added ability to remove agents from management interface
  • Added persistence for page size and sorting in tables
  • Improved Agent Overview resilience

​
Wazuh 4.13.x

Key Changes:
  • Added IT Hygiene application
  • Added hardware and system information to agent overview
  • Added persistence for selected columns in data grids
  • Added ability to manage sample data

​
Troubleshooting Upgrade Issues

​
Dashboard Fails to Start After Upgrade

Symptoms: Service fails to start or crashes immediately after upgrade. Solutions:
  1. Check service status:
systemctl status wazuh-dashboard
  1. Review logs:
sudo tail -100 /var/log/wazuh-dashboard/opensearch_dashboards.log
  1. Verify configuration syntax:
sudo /usr/share/wazuh-dashboard/bin/opensearch-dashboards --validate-config
  1. Check file permissions:
ls -la /etc/wazuh-dashboard/
ls -la /usr/share/wazuh-dashboard/

​
Configuration Not Applied

Symptoms: Settings from configuration file are not taking effect. Solutions:
  1. Verify configuration file location and syntax
  2. Ensure no duplicate settings
  3. Check for typos in setting keys
  4. Restart the service after configuration changes
  5. Clear browser cache and cookies

​
Plugin Compatibility Issues

Symptoms: Dashboard displays plugin errors or fails to load certain features. Solutions:
  1. List all installed plugins:
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list
  1. Remove incompatible plugins:
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin remove <PLUGIN_NAME>
  1. Clear optimization cache:
sudo rm -rf /usr/share/wazuh-dashboard/optimize/bundles/*
sudo systemctl restart wazuh-dashboard

​
Saved Objects Import Fails

Symptoms: Error when importing exported saved objects. Solutions:
  1. Verify the .ndjson file is not corrupted
  2. Check for version compatibility issues
  3. Import objects in smaller batches
  4. Use “Automatically overwrite conflicts” option
  5. Manually create conflicting objects first

​
Performance Degradation After Upgrade

Symptoms: Dashboard is slower than before the upgrade. Solutions:
  1. Clear browser cache
  2. Optimize indices:
curl -X POST "https://localhost:9200/_forcemerge?max_num_segments=1" -u admin:admin -k
  1. Review resource utilization:
free -h
df -h
top
  1. Check indexer performance
  2. Review dashboard configuration for optimization opportunities

​
Rollback Procedure

Only perform a rollback if the upgrade fails and cannot be fixed through troubleshooting.
If you need to rollback to the previous version:
  1. Stop the dashboard service:
sudo systemctl stop wazuh-dashboard
  1. Downgrade the package:
Debian/Ubuntu: 
sudo apt-get install wazuh-dashboard=<PREVIOUS_VERSION> --allow-downgrades
RHEL/CentOS: 
sudo yum downgrade wazuh-dashboard-<PREVIOUS_VERSION>
  1. Restore configuration backup:
sudo cp /etc/wazuh-dashboard/opensearch_dashboards.yml.old /etc/wazuh-dashboard/opensearch_dashboards.yml
  1. Restart the service:
sudo systemctl start wazuh-dashboard
  1. Verify functionality and import saved objects if needed

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us