> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/wazuh/wazuh-dashboard-plugins/llms.txt
> Use this file to discover all available pages before exploring further.

# Upgrade Procedures

> Step-by-step guide for upgrading Wazuh Dashboard Plugins to newer versions

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

```bash theme={null}
systemctl stop wazuh-dashboard
```

**SysV init**:

```bash theme={null}
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:

```bash theme={null}
cp /etc/wazuh-dashboard/opensearch_dashboards.yml /etc/wazuh-dashboard/opensearch_dashboards.yml.old
```

### Upgrade the Package

**Yum (RHEL/CentOS)**:

```bash theme={null}
yum upgrade wazuh-dashboard-5.0.0-1
```

**APT (Debian/Ubuntu)**:

```bash theme={null}
apt-get install wazuh-dashboard=5.0.0-1
```

> [!NOTE]
>
> 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:

```yaml theme={null}
uiSettings.overrides.defaultRoute: /app/wz-home
```

### Restart the Dashboard

**Systemd**:

```bash theme={null}
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**:

```bash theme={null}
chkconfig --add wazuh-dashboard
service wazuh-dashboard start
```

* **Debian-based operating system**:

```bash theme={null}
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

> [!WARNING]
>
> 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)](/guides/migration-4x-5x) for detailed migration steps.

## Managing Plugins

> [!NOTE]
>
> 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:

```bash theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
systemctl status wazuh-dashboard
```

2. Review logs:

```bash theme={null}
sudo tail -100 /var/log/wazuh-dashboard/opensearch_dashboards.log
```

3. Verify configuration syntax:

```bash theme={null}
sudo /usr/share/wazuh-dashboard/bin/opensearch-dashboards --validate-config
```

4. Check file permissions:

```bash theme={null}
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:

```bash theme={null}
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin list
```

2. Remove incompatible plugins:

```bash theme={null}
sudo -u wazuh-dashboard /usr/share/wazuh-dashboard/bin/opensearch-dashboards-plugin remove <PLUGIN_NAME>
```

3. Clear optimization cache:

```bash theme={null}
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:

```bash theme={null}
curl -X POST "https://localhost:9200/_forcemerge?max_num_segments=1" -u admin:admin -k
```

3. Review resource utilization:

```bash theme={null}
free -h
df -h
top
```

4. Check indexer performance
5. Review dashboard configuration for optimization opportunities

## Rollback Procedure

> [!WARNING]
>
> 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:

```bash theme={null}
sudo systemctl stop wazuh-dashboard
```

2. Downgrade the package:

**Debian/Ubuntu**:

```bash theme={null}
sudo apt-get install wazuh-dashboard=<PREVIOUS_VERSION> --allow-downgrades
```

**RHEL/CentOS**:

```bash theme={null}
sudo yum downgrade wazuh-dashboard-<PREVIOUS_VERSION>
```

3. Restore configuration backup:

```bash theme={null}
sudo cp /etc/wazuh-dashboard/opensearch_dashboards.yml.old /etc/wazuh-dashboard/opensearch_dashboards.yml
```

4. Restart the service:

```bash theme={null}
sudo systemctl start wazuh-dashboard
```

5. Verify functionality and import saved objects if needed

## Additional Resources

* **Official upgrade documentation**: [https://documentation.wazuh.com/current/upgrade-guide/index.html](https://documentation.wazuh.com/current/upgrade-guide/index.html)
* **Release notes**: Check the CHANGELOG for version-specific changes
* **Community support**: [https://groups.google.com/g/wazuh](https://groups.google.com/g/wazuh)
* **GitHub issues**: [https://github.com/wazuh/wazuh-dashboard-plugins/issues](https://github.com/wazuh/wazuh-dashboard-plugins/issues)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.