Health Module

The health module performs comprehensive health checks on the server and reports status to the Bloqd dashboard.

Health Checks

The module runs the following checks:

Configuration Checks

Check	Description	Critical?
config_file	Config file exists	Yes
api_url	API URL is configured	Yes
api_key	API key is configured	Yes
config_permissions	Config file has secure permissions	Warning

Module Checks

Check	Description	Critical?
last_sync	Last whitelist sync was successful	Warning
health_timer	Health module is running	Yes

fail2ban Checks

Check	Description	Critical?
fail2ban_running	fail2ban service is running	Yes
active_jails	At least one jail is active	Warning

System Checks

Check	Description	Critical?
disk_usage	Disk usage within thresholds	Configurable
memory_usage	Memory usage within thresholds	Configurable

Connectivity Checks

Check	Description	Critical?
api_reachable	Can reach Bloqd server	Yes
api_auth	API authentication works	Yes

Other Checks

Check	Description	Critical?
report_socket	Reporter socket exists	Warning

Configuration

modules:
  health:
    enabled: true
    interval: 60  # 1 minute
    checks:
      - fail2ban_running
      - disk_space
      - memory_usage
    disk_warning_percent: 80
    disk_critical_percent: 90
    memory_warning_percent: 80
    memory_critical_percent: 95

Setting	Description	Default
enabled	Enable health checks	true
interval	Check interval (seconds)	60
checks	List of checks to run	All checks
disk_warning_percent	Disk warning threshold	80
disk_critical_percent	Disk critical threshold	90
memory_warning_percent	Memory warning threshold	80
memory_critical_percent	Memory critical threshold	95

Health Status Levels

Status	Description	Dashboard Color
healthy	All checks passed	Green
warning	Some checks have warnings	Yellow
critical	Critical checks failed	Red
unknown	Unable to determine status	Gray

How It Works

1. Module runs checks at configured interval
2. Each check returns a status and message
3. Overall status is calculated (worst status wins)
4. Results are sent to server
5. Dashboard updates server health indicator

┌─────────────────┐
│  Health Module  │
└────────┬────────┘
         │
    ┌────┼────┬────────┬────────┐
    ▼    ▼    ▼        ▼        ▼
┌──────┐┌────┐┌────────┐┌──────┐┌───────┐
│Config││Disk││fail2ban││Memory││Network│
└──┬───┘└─┬──┘└───┬────┘└──┬───┘└───┬───┘
   │      │       │        │        │
   └──────┴───────┴────────┴────────┘
                  │
                  ▼
          ┌──────────────┐
          │ Bloqd Server │
          │ (health API) │
          └──────────────┘

Running Manual Health Check

# Run health check with debug output
bloqd-agent --health-check

Output example:

============================================================
BLOQD AGENT HEALTH CHECK (v2.0.0)
============================================================

Config file: /etc/bloqd/agent.yaml
Server URL:  https://bloqd.example.com
Hostname:    web-server-01

[1/4] Registering with server...
      ✓ Registered as server_id: 5

[2/4] Running health checks...
      ✓ config_file: Config file exists
      ✓ api_url: API URL configured
      ✓ api_key: API Key configured
      ✓ config_permissions: Config permissions secure
      ✓ last_sync: Last sync successful
      ✓ health_timer: Health timer running
      ✓ fail2ban_running: fail2ban running
      ✓ active_jails: 3 active jails
      ✓ disk_usage: Disk usage normal
      ✓ memory_usage: Memory usage normal
      ✓ api_reachable: API reachable
      ✓ api_auth: API authentication OK
      ✓ report_socket: Report socket OK

      Summary: 13 passed, 0 warnings, 0 failed

[3/4] Preparing payload...
      Endpoint: POST https://bloqd.example.com/api/v1/server-health/servers/5
      Payload:
      {
        "status": "healthy",
        "checks": {
          "passed": [...],
          "failed": [],
          "warnings": []
        }
      }

[4/4] Sending to backend...
      ✓ Success!

============================================================
Health check complete!
============================================================

Events

Event	Direction	Description
health_status_changed	Emits	Status changed (e.g., healthy → warning)

API Payload

Health status is sent to the server:

{
  "status": "healthy",
  "checks": {
    "passed": [
      "Config file exists",
      "API URL configured",
      "fail2ban running",
      "Disk usage normal"
    ],
    "failed": [],
    "warnings": [],
    "results": {
      "config_file": {
        "status": "healthy",
        "message": "Config file exists"
      },
      "disk_usage": {
        "status": "healthy",
        "message": "Disk usage normal"
      }
    }
  },
  "summary": "13 passed, 0 warnings, 0 failed"
}

Dashboard Display

Health status appears in multiple places:

1. Server List: Health indicator dot next to server name
2. Server Detail: Health tab with full check results
3. Dashboard Overview: Server health summary widget

Troubleshooting

Health Shows Critical

1. Check which checks failed:

   bloqd-agent --health-check

2. Common causes:

   • fail2ban not running
   • API key invalid
   • Server unreachable
   • Config file missing

Disk/Memory Warnings

Adjust thresholds if needed:

modules:
  health:
    disk_warning_percent: 85
    disk_critical_percent: 95

Health Not Updating

1. Check agent is running:

   systemctl status bloqd-agent

2. Check logs:

   journalctl -u bloqd-agent | grep -i health

3. Verify interval setting