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

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

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

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

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

```typescript theme={null}
{
  period: {
    interval: 1,
    unit: 'MINUTES'
  }
}
```

**Data Source:**

```typescript theme={null}
{
  indices: ['wazuh-events*']
}
```

**Query:**

```typescript theme={null}
{
  size: 100,
  query: {
    match_all: {}
  }
}
```

**Trigger Condition:**

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

```bash theme={null}
/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](/configuration/authentication)
* [Plugin Settings](/configuration/settings)
* [Notifications and Alerting](/configuration/notifications-alerting)


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