Health Check System

Understanding the Wazuh Dashboard health check system and initialization tasks

The Wazuh Dashboard includes a comprehensive health check system that ensures all required components, configurations, and integrations are properly initialized before the application becomes fully operational.

Overview

The health check system performs automated verification and initialization tasks during Dashboard startup and runtime. These tasks ensure:

• Index patterns exist and have correct field mappings
• Wazuh Server API connections are reachable and compatible
• Required saved objects and templates are created
• Notification channels are configured for alerting
• Alerting monitors are created for integrations
• Authentication modes are properly configured

Health Check Execution Contexts

Health check tasks execute in different contexts depending on the trigger:

Internal Context

Tasks run automatically by the system during initialization or scheduled intervals.

Types:

• internal-initial - First-time initialization tasks
• internal-scheduled - Periodic maintenance tasks
• internal - General internal tasks

User Context

Tasks triggered by user actions, such as navigating to a specific dashboard section or explicitly requesting a health check.

Type:

• user - User-initiated tasks

Health Check Components

Index Patterns

The health check system ensures all required index patterns exist and have correct field mappings.

Verified Index Patterns

• Events: wazuh-events*
• Monitoring: wazuh-monitoring*
• Statistics: wazuh-statistics*
• Vulnerabilities: wazuh-states-vulnerabilities*
• File Integrity Monitoring: wazuh-states-fim*
• Security Configuration Assessment: wazuh-states-sca*
• Inventory/IT Hygiene: wazuh-states-inventory*

Index Pattern Tasks

Creation:

If an index pattern does not exist, the health check creates it with appropriate field mappings.

Field Mapping Verification:

The system retrieves field mappings from matching indices and creates the index pattern with the correct schema.

Pre-defined Fields:

If matching indices do not exist, some index patterns are created with pre-defined field sets to support future data ingestion.

Time Field Assignment:

Index patterns are configured with the appropriate time field (typically @timestamp) for time-based filtering.

Server API Connection Compatibility

The health check verifies connectivity and version compatibility with configured Wazuh Server API hosts.

Compatibility Checks

Version Matching:

The Dashboard and Wazuh Server API versions are compared. Major and minor version numbers must match for compatibility.

Example:

• Dashboard version: 4.5.2
• Server API version: v4.5.1
• Result: Compatible (major: 4, minor: 5 match)

Connection Verification:

The system attempts to connect to each configured API host and retrieve version information.

Multiple Host Support:

When multiple API hosts are configured, the health check verifies each host independently. At least one compatible and reachable host is required for successful initialization.

Health Check Results

For each API host, the health check returns:

{
  id: string;              // API host identifier
  connection: boolean;     // Connection status
  compatibility: boolean;  // Version compatibility
  api_version: string;     // Server API version
}

Error Handling

If no compatible API hosts are available:

Error: No server API available to connect. Ensure at least a server API is reachable 
and compatible with the dashboard. Review the server API hosts configuration, ensure 
the service is up, is reachable and compatible with the dashboard.

Run As Authentication Check

The health check verifies that the run_as authentication mode is properly configured when enabled.

Run As Status Values

Status	Description
Enabled	Run as is allowed for both user and host
Host Disabled	Run as is disabled in the Wazuh Server configuration
All Disabled	Run as is disabled in both host and user configuration
User Not Allowed	Run as is not permitted for the configured user
Unable to Check	Cannot determine run_as permission status

Verification Process

1. Retrieve all configured API hosts
2. Check the allow_run_as value from cluster information
3. Determine if run_as is enabled for each host
4. Log warnings for hosts where run_as is not enabled
5. Return list of hosts with run_as enabled

Error Handling

If run_as is required but not enabled:

Error: Some server API hosts have not enabled the run_as or the user has no the 
ability to use it or both are not enabled: [host-id] (status). Ensure every 
configured API host allows run_as for the API user.

Templates

The health check ensures required OpenSearch index templates are created for Wazuh data.

Template Name: wazuh-kibana

Purpose: Defines default settings and mappings for Wazuh indices

Saved Objects

The system verifies and creates required saved objects, including:

• Visualizations
• Dashboards
• Searches
• Configuration objects

Notification Channels

The health check can automatically create default notification channels for common integrations.

Supported Channels

• Slack: Webhook-based notifications to Slack channels
• PagerDuty: Incident creation via PagerDuty Events API
• Jira: Issue creation in Jira projects
• Shuffle: Automation workflow triggers

Default Channel Configuration

Channels are created with placeholder configurations that must be updated with actual credentials:

Slack:

{
  config_id: 'wazuh-slack',
  name: 'Wazuh Slack',
  config_type: 'slack',
  is_enabled: true,
  slack: {
    url: 'https://hooks.slack.com/services/REPLACE/WITH/YOUR_WEBHOOK'
  }
}

PagerDuty:

{
  config_id: 'wazuh-pagerduty',
  name: 'Wazuh PagerDuty',
  config_type: 'webhook',
  is_enabled: true,
  webhook: {
    url: 'https://events.pagerduty.com/v2/enqueue'
  }
}

Channel Verification

Before creating a new channel, the health check:

1. Queries existing notification configurations
2. Checks if a channel with the target ID already exists
3. Skips creation if the channel exists
4. Creates the channel if it does not exist

Alerting Monitors

The health check creates sample alerting monitors for testing notification integrations.

Sample Monitors

• Sample: Slack - Test monitor for Slack notifications
• Sample: PagerDuty - Test monitor for PagerDuty incidents
• Sample: Jira - Test monitor for Jira issue creation
• Sample: Shuffle - Test monitor for Shuffle workflows

Monitor Components

Schedule:

{
  period: {
    interval: 1,
    unit: 'MINUTES'
  }
}

Data Source:

{
  indices: ['wazuh-events*']
}

Query:

{
  size: 100,
  query: {
    match_all: {}
  }
}

Trigger Condition:

return ctx.results[0].hits.total.value > 0

Severity: 1 (Critical)

Conditional Creation

Monitors are only created if the corresponding notification channel exists. This prevents monitors from being created without valid notification destinations.

Health Check Workflow

Initialization Sequence

1. System Startup

   • Dashboard service starts
   • Health check system initializes

2. Context Determination

   • Identify execution context (internal vs. user)
   • Load relevant task list

3. Task Execution

   • Execute tasks in defined order
   • Each task performs verification and initialization
   • Log results and errors

4. Result Aggregation

   • Collect results from all tasks
   • Determine overall health status
   • Report success or failure

5. Error Handling

   • Critical errors prevent Dashboard startup
   • Warnings are logged but allow continued operation
   • User-facing error messages guide remediation

Task Dependencies

Some tasks depend on others and execute in sequence:

1. Server API connection verification must succeed before other API-dependent tasks
2. Index patterns must be created before related saved objects
3. Notification channels must exist before monitors are created

Monitoring Health Check Status

Log Files

Health check activity is logged to the Dashboard log file:

/var/log/wazuh-dashboard/wazuh-dashboard.log

Log Messages

Successful Task:

Starting check server API connection and compatibility
APP version [4.5.2]
Checking the connection and compatibility with server API [production]
Server API version [v4.5.1]
Server API [production] version [v4.5.1] is compatible with the Dashboard version
Start check server API connection and compatibility finished

Failed Task:

Error checking server API connection and compatibility: No server API available to connect

Warning:

Server API hosts have not enabled the run_as: production (Run as disabled in host)

Health Check UI

The Dashboard may display health check status and errors in the user interface:

• Health Check Screen: Displayed when critical initialization fails
• Status Indicators: Show component health in the interface
• Error Messages: Provide actionable guidance for resolving issues

Common Health Check Issues

Index Pattern Creation Failures

Symptom:

Fields for index pattern with ID [wazuh-events*] could not be obtained

Cause: No matching indices exist, or there is an error retrieving field mappings

Resolution:

1. Verify Wazuh agents are sending data
2. Check that the Wazuh indexer is properly configured
3. Confirm index creation is working
4. Review indexer logs for errors

API Connection Failures

Symptom:

Error checking the connection and compatibility with server API [production]: 
Connection refused

Cause: Cannot connect to the Wazuh Server API

Resolution:

1. Verify the Wazuh Server API service is running
2. Check network connectivity
3. Validate the URL and port in configuration
4. Review firewall rules
5. Verify SSL/TLS certificates if using HTTPS

Version Incompatibility

Symptom:

Server API [production] version [v4.3.0] is not compatible with the Dashboard 
version [4.5.2]

Cause: Major or minor version numbers do not match

Resolution:

1. Update the Wazuh Server to match the Dashboard version
2. Or downgrade the Dashboard to match the Server version
3. Ensure all components are running compatible versions

Run As Configuration Issues

Symptom:

Some server API hosts have not enabled the run_as: production (Run as disabled 
in host)

Cause: The Wazuh Server API does not have allow_run_as enabled

Resolution:

1. Edit the Wazuh Server configuration
2. Enable allow_run_as in the API settings
3. Restart the Wazuh Server API service
4. Restart the Dashboard to re-run health checks

Notification Channel Creation Failures

Symptom: Notification channels are not created during initialization

Cause: OpenSearch Notifications plugin is not available or misconfigured

Resolution:

1. Verify the Notifications plugin is installed
2. Check OpenSearch logs for plugin errors
3. Manually create notification channels if automatic creation fails

Disabling Health Checks

Warning: Disabling health checks is not recommended for production environments.

Health checks ensure system integrity and proper configuration. Disabling them may result in:

• Missing or incorrectly configured index patterns
• Incompatible API connections causing errors
• Missing required saved objects and visualizations
• Non-functional notification and alerting features

If you must disable specific health check tasks for troubleshooting, consult the Wazuh support team or community forums.

Best Practices

1. Monitor Logs: Regularly review Dashboard logs for health check warnings
2. Version Compatibility: Keep all Wazuh components at compatible versions
3. Network Connectivity: Ensure reliable connectivity between components
4. Test After Updates: Verify health checks pass after system updates
5. Document Custom Configurations: Track any customizations that affect health checks

Related Topics

• Authentication Setup
• Plugin Settings
• Notifications and Alerting