Migration Guide (4.x to 5.x) - Wazuh Dashboard Plugins

This comprehensive guide covers migrating the Wazuh dashboard plugins from version 4.x to 5.x, including breaking changes, configuration updates, and troubleshooting steps.

Overview

Wazuh 5.x introduces significant changes to the dashboard plugins architecture and configuration:

Platform upgrade: Migration from Kibana/OpenSearch Dashboards 2.x to OpenSearch Dashboards 3.x
Configuration changes: Settings relocated from wazuh.yml to opensearch_dashboards.yml
Plugin restructure: Core functionality split into modular plugins (wazuh-core, wazuh-check-updates)
Index pattern updates: New default pattern wazuh-events* replacing wazuh-alerts-*
UI modernization: Removal of legacy interfaces and deprecated features
Security enhancements: Updated authentication and authorization mechanisms

Compatibility Matrix

Wazuh Version	Dashboard Platform	Indexer Version	Manager Version
4.x	OpenSearch Dashboards 2.x	OpenSearch 2.x	Wazuh 4.x
5.0.x	OpenSearch Dashboards 3.x	OpenSearch 3.x	Wazuh 5.x

All Wazuh stack components (indexer, manager, dashboard) must be upgraded to 5.x together. Mixed-version deployments are not supported.

Pre-Migration Preparation

Review System Requirements

Verify your system meets 5.x requirements:

OS: Supported Linux distribution
Hardware: Minimum 4 GB RAM, 8 GB recommended
Network: Connectivity to upgraded indexer and manager
Certificates: Valid TLS certificates compatible with OpenSearch 3.x

Back Up Critical Data

Before starting the migration:

Back up saved objects

Navigate to ☰ Menu > Dashboard Management > Saved objects
Click Export all
Save the exported .ndjson file to a safe location
Alternatively, use the API:

curl -X POST "https://localhost:5601/api/saved_objects/_export" \
  -H "osd-xsrf: true" \
  -H "Content-Type: application/json" \
  -u admin:admin \
  -d '{"type": ["dashboard", "visualization", "search", "index-pattern"]}' \
  -o saved-objects-backup-$(date +%Y%m%d).ndjson

Back up configuration files

# Dashboard configuration
sudo cp -a /etc/wazuh-dashboard/ /root/backup-wazuh-dashboard-$(date +%Y%m%d)/

# Plugin-specific config (if exists)
sudo cp /usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml \
   /root/backup-wazuh-config-$(date +%Y%m%d).yml

Back up certificates

sudo cp -a /etc/wazuh-dashboard/certs/ /root/backup-certs-$(date +%Y%m%d)/

Document custom settings

# Extract custom settings from opensearch_dashboards.yml
grep -v "^#" /etc/wazuh-dashboard/opensearch_dashboards.yml | grep -v "^$" \
  > custom-settings-$(date +%Y%m%d).txt

Review Breaking Changes

Review the CHANGELOG and note:

Deprecated settings that must be removed
Renamed configuration keys
Removed features you may be using
New required configurations

Breaking Changes in 5.x

Configuration File Changes

wazuh.yml deprecated

The standalone wazuh.yml configuration file is removed in 5.x. All plugin settings have been moved to:

opensearch_dashboards.yml - Core settings
Advanced Settings UI - Tenant-level preferences

Migration path: 4.x (/usr/share/wazuh-dashboard/data/wazuh/config/wazuh.yml):

hosts:
  - id: default
    url: https://wazuh-manager
    port: 55000
    username: wazuh-wui
    password: wazuh-wui
    run_as: false

pattern: wazuh-alerts-*

timeout: 20000

api.selector: true

ip.selector: true

5.x (/etc/wazuh-dashboard/opensearch_dashboards.yml):

wazuh_core.hosts:
  default:
    url: https://wazuh-manager
    port: 55000
    username: wazuh-wui
    password: wazuh-wui
    run_as: false

5.x (Advanced Settings UI):

Navigate to ☰ Menu > Dashboard Management > Advanced Settings
Configure tenant-level settings:
- timeout: 20000
- Other UI preferences

Index Pattern Changes

4.x Setting	5.x Equivalent	Notes
`pattern: wazuh-alerts-*`	`wazuh-events*`	Default changed; update if customized
`wazuh.monitoring.pattern`	Advanced Settings	Configure in UI, not config file

Removed Settings

These settings are no longer supported and must be removed from your configuration.

# Removed in 5.x - do NOT include
customization.enabled: true
customization.logo.app: /custom/logo.svg
customization.logo.healthcheck: /custom/healthcheck.svg
wazuh.monitoring.creation: h
wazuh.monitoring.shards: 1
wazuh.monitoring.replicas: 0
admin: true

Replacement:

Custom branding: Use opensearchDashboards.branding.*
Monitoring: Configured via index lifecycle management
Admin mode: Replaced by role-based access control

Plugin Architecture Changes

New Plugin Structure

4.x	5.x
Single `wazuh` plugin	`wazuh` (main), `wazuh-core` (shared), `wazuh-check-updates`

Impact: Plugin dependencies are automatically managed. No manual action required.

API Changes

If you have custom scripts or integrations:

4.x Endpoint	5.x Equivalent
`/api/status`	`/api/wazuh-core/status`
`/api/check-updates`	`/api/wazuh-check-updates/updates`
`/api/timestamp`	`/api/wazuh-core/timestamp`

UI Changes

Removed Features

Legacy App Settings: Use ☰ Menu > Dashboard Management > Advanced Settings or opensearch_dashboards.yml
Dev Tools integration: Use native OpenSearch Dashboards Dev Tools
Deprecated modules: Some 4.x experimental modules removed

4.x Path	5.x Path
`/app/wazuh#/overview`	`/app/wz-home`
`/app/wazuh#/settings`	Dashboard Management > Advanced Settings
`/app/wazuh#/health-check`	☰ Menu > Management > Health Check

Migration Steps

Step 1: Upgrade Stack Components in Order

Follow this sequence to avoid compatibility issues:

1.1 Upgrade Wazuh indexer (first)

# Stop Wazuh dashboard first
sudo systemctl stop wazuh-dashboard

# Upgrade indexer
sudo apt-get update && sudo apt-get install wazuh-indexer=5.0.0-1  # Debian/Ubuntu
# OR
sudo yum install wazuh-indexer-5.0.0-1  # RHEL/CentOS

# Restart indexer
sudo systemctl restart wazuh-indexer

# Verify indexer health
curl -k -u admin:admin https://localhost:9200/_cluster/health?pretty

1.2 Upgrade Wazuh manager (second)

# Upgrade manager
sudo apt-get install wazuh-manager=5.0.0-1  # Debian/Ubuntu
# OR
sudo yum install wazuh-manager-5.0.0-1  # RHEL/CentOS

# Restart manager
sudo systemctl restart wazuh-manager

# Verify manager status
sudo systemctl status wazuh-manager

1.3 Upgrade Wazuh dashboard (last)

# Upgrade dashboard package
sudo apt-get install wazuh-dashboard=5.0.0-1  # Debian/Ubuntu
# OR
sudo yum install wazuh-dashboard-5.0.0-1  # RHEL/CentOS

# Do NOT start yet - configure first

Step 2: Migrate Configuration

2.1 Update opensearch_dashboards.yml

Edit /etc/wazuh-dashboard/opensearch_dashboards.yml:

sudo nano /etc/wazuh-dashboard/opensearch_dashboards.yml

Required changes:

Update server settings (if customized):

server.host: '0.0.0.0'
server.port: 443
server.name: 'wazuh-dashboard'

Update indexer connection:

opensearch.hosts: ['https://localhost:9200']
opensearch.ssl.verificationMode: certificate

Add Wazuh API configuration (migrated from wazuh.yml):

wazuh_core.hosts:
  default:
    url: https://localhost
    port: 55000
    username: wazuh-wui
    password: wazuh-wui
    run_as: false

Set default route:

opensearchDashboards.defaultAppId: wz-home

Remove deprecated settings (if present):

Remove any lines containing:

customization.*
wazuh.monitoring.*
admin

2.2 Update Certificate Paths

Verify certificate paths in opensearch_dashboards.yml:

server.ssl.enabled: true
server.ssl.certificate: /etc/wazuh-dashboard/certs/dashboard.crt
server.ssl.key: /etc/wazuh-dashboard/certs/dashboard.key

opensearch.ssl.certificateAuthorities:
  ['/etc/wazuh-dashboard/certs/root-ca.pem']

2.3 Apply Custom Branding

Migrate customization.* settings to OpenSearch Dashboards branding: 4.x custom branding:

# Old - remove from config
customization.enabled: true
customization.logo.app: /custom/logo.svg

5.x branding:

opensearchDashboards.branding.logo:
  defaultUrl: 'https://example.com/logo.svg'
opensearchDashboards.branding.mark:
  defaultUrl: 'https://example.com/icon.svg'
opensearchDashboards.branding.applicationTitle: 'Custom Security Dashboard'

Step 3: Update File Permissions

# Ensure correct ownership
sudo chown -R wazuh-dashboard:wazuh-dashboard /usr/share/wazuh-dashboard/
sudo chown -R wazuh-dashboard:wazuh-dashboard /etc/wazuh-dashboard/
sudo chown -R wazuh-dashboard:wazuh-dashboard /var/lib/wazuh-dashboard/

# Set secure permissions
sudo chmod 640 /etc/wazuh-dashboard/opensearch_dashboards.yml
sudo chmod 600 /etc/wazuh-dashboard/certs/*.key

Step 4: Start and Verify Dashboard

# Start dashboard
sudo systemctl daemon-reload
sudo systemctl enable wazuh-dashboard
sudo systemctl start wazuh-dashboard

# Monitor startup logs
sudo tail -f /var/log/wazuh-dashboard/opensearch_dashboards.log

Look for successful startup messages:

[info][server][OpenSearchDashboards] http server running at https://0.0.0.0:443
[info][plugins][wazuh] Wazuh plugin initialized

Step 5: Import Saved Objects

Log in to the dashboard at https://your-dashboard-ip/
Navigate to ☰ Menu > Dashboard Management > Saved objects
Click Import
Select your backed-up .ndjson file
Handle conflicts:
- Check for existing objects: Recommended for most cases
- Automatically overwrite: Use with caution
Click Import

Post-Migration Validation

Verify Dashboard Functionality

✅ Check list:

Dashboard loads at /app/wz-home
Wazuh logo and branding appear correctly
Navigation menu displays all modules
Agents list loads successfully
Events are displayed in Threat Hunting

Run Health Check

Navigate to ☰ Menu > Management > Health Check
Click Check
Verify all checks pass:
- ✅ API connection
- ✅ Indexer connection
- ✅ Plugin status
- ✅ Index patterns
- ✅ Template verification

Validate API Connections

Test Wazuh manager API connectivity:

# From dashboard server
curl -k -u wazuh-wui:wazuh-wui https://localhost:55000/

Expected response:

{
  "data": {
    "title": "Wazuh API REST",
    "api_version": "5.0.0",
    "revision": 50000,
    "hostname": "wazuh-manager",
    "timestamp": "2026-02-24T10:00:00Z"
  }
}

Verify Index Patterns

Navigate to ☰ Menu > Dashboard Management > Index patterns:

Default pattern wazuh-events* exists
Time field is timestamp
Field mappings are loaded

Troubleshooting Common Migration Issues

Issue 1: Dashboard Fails to Start

Symptoms:

[error][savedobjects-service] Unable to connect to OpenSearch

Solutions:

Verify indexer is running:

sudo systemctl status wazuh-indexer
curl -k -u admin:admin https://localhost:9200/

Check certificate paths:

ls -la /etc/wazuh-dashboard/certs/

Test indexer connectivity:

openssl s_client -connect localhost:9200 -CAfile /etc/wazuh-dashboard/certs/root-ca.pem

Review logs:

sudo tail -100 /var/log/wazuh-dashboard/opensearch_dashboards.log

Issue 2: API Connection Errors

Symptoms:

Wazuh API is not reachable

Solutions:

Verify API configuration in opensearch_dashboards.yml:

grep -A 10 "wazuh_core.hosts:" /etc/wazuh-dashboard/opensearch_dashboards.yml

Test API manually:

curl -k -u wazuh-wui:wazuh-wui https://localhost:55000/

Check manager firewall:

sudo firewall-cmd --list-all  # RHEL/CentOS
sudo ufw status  # Ubuntu

Issue 3: Missing Saved Objects

Symptoms: Dashboards or visualizations do not appear after migration. Solutions:

Re-import saved objects:
- Go to Dashboard Management > Saved objects > Import
- Select backed-up .ndjson file
- Choose Automatically overwrite conflicts
Manually create index pattern if missing:

curl -X POST "https://localhost:5601/api/saved_objects/index-pattern/wazuh-events" \
  -H "osd-xsrf: true" \
  -H "Content-Type: application/json" \
  -u admin:admin \
  -d '{
    "attributes": {
      "title": "wazuh-events*",
      "timeFieldName": "timestamp"
    }
  }'

Regenerate default objects:
- Navigate to Management > Health Check
- Click Check to recreate missing templates and patterns

Issue 4: Performance Degradation

Symptoms: Dashboard is slow or unresponsive after migration. Solutions:

Clear browser cache and cookies
Optimize OpenSearch indices:

curl -X POST "https://localhost:9200/wazuh-events*/_forcemerge?max_num_segments=1" \
  -u admin:admin -k

Review resource allocation:

# Check memory usage
free -h
# Check disk space
df -h

Tune dashboard settings in opensearch_dashboards.yml:

ops.interval: 10000 # Increase monitoring interval
opensearch.requestTimeout: 60000 # Increase timeout

Rollback Procedure

Rollback is complex and may result in data loss. Only perform if absolutely necessary.

If migration fails and you need to rollback:

1. Stop 5.x Dashboard

sudo systemctl stop wazuh-dashboard

2. Downgrade Package

# Debian/Ubuntu
sudo apt-get install wazuh-dashboard=4.9.0-1 --allow-downgrades

# RHEL/CentOS
sudo yum downgrade wazuh-dashboard-4.9.0-1

3. Restore Configuration

sudo rm -rf /etc/wazuh-dashboard/
sudo cp -a /root/backup-wazuh-dashboard-YYYYMMDD/ /etc/wazuh-dashboard/

4. Rollback Stack Components

Follow the same procedure for indexer and manager (in reverse order).

5. Restart Services

sudo systemctl start wazuh-dashboard

Additional Resources

Official migration guide: https://documentation.wazuh.com/current/upgrade-guide/index.html
Community forum: https://groups.google.com/g/wazuh
GitHub issues: https://github.com/wazuh/wazuh-dashboard-plugins/issues
Official documentation: https://documentation.wazuh.com/

​Overview

​Compatibility Matrix

​Pre-Migration Preparation

​Review System Requirements

​Back Up Critical Data

​Back up saved objects

​Back up configuration files

​Back up certificates

​Document custom settings

​Review Breaking Changes

​Breaking Changes in 5.x

​Configuration File Changes

​wazuh.yml deprecated

​Index Pattern Changes

​Removed Settings

​Plugin Architecture Changes

​New Plugin Structure

​API Changes

​UI Changes

​Removed Features

​Renamed Navigation Paths

​Migration Steps

​Step 1: Upgrade Stack Components in Order

​1.1 Upgrade Wazuh indexer (first)

​1.2 Upgrade Wazuh manager (second)

​1.3 Upgrade Wazuh dashboard (last)

​Step 2: Migrate Configuration

​2.1 Update opensearch_dashboards.yml

​2.2 Update Certificate Paths

​2.3 Apply Custom Branding

​Step 3: Update File Permissions

​Step 4: Start and Verify Dashboard

​Step 5: Import Saved Objects

​Post-Migration Validation

​Verify Dashboard Functionality

​Run Health Check

​Validate API Connections

​Verify Index Patterns

​Troubleshooting Common Migration Issues

​Issue 1: Dashboard Fails to Start

​Issue 2: API Connection Errors

​Issue 3: Missing Saved Objects

​Issue 4: Performance Degradation

​Rollback Procedure

​1. Stop 5.x Dashboard

​2. Downgrade Package

​3. Restore Configuration

​4. Rollback Stack Components

​5. Restart Services

​Additional Resources

Overview

Compatibility Matrix

Pre-Migration Preparation

Review System Requirements

Back Up Critical Data

Back up saved objects

Back up configuration files

Back up certificates

Document custom settings

Review Breaking Changes

Breaking Changes in 5.x

Configuration File Changes

wazuh.yml deprecated

Index Pattern Changes

Removed Settings

Plugin Architecture Changes

New Plugin Structure

API Changes

UI Changes

Removed Features

Renamed Navigation Paths

Migration Steps

Step 1: Upgrade Stack Components in Order

1.1 Upgrade Wazuh indexer (first)

1.2 Upgrade Wazuh manager (second)

1.3 Upgrade Wazuh dashboard (last)

Step 2: Migrate Configuration

2.1 Update opensearch_dashboards.yml

2.2 Update Certificate Paths

2.3 Apply Custom Branding

Step 3: Update File Permissions

Step 4: Start and Verify Dashboard

Step 5: Import Saved Objects

Post-Migration Validation

Verify Dashboard Functionality

Run Health Check

Validate API Connections

Verify Index Patterns

Troubleshooting Common Migration Issues

Issue 1: Dashboard Fails to Start

Issue 2: API Connection Errors

Issue 3: Missing Saved Objects

Issue 4: Performance Degradation

Rollback Procedure

1. Stop 5.x Dashboard

2. Downgrade Package

3. Restore Configuration

4. Rollback Stack Components

5. Restart Services

Additional Resources