Monitoring ioBroker with Vigilmon

ioBroker is the open-source home automation platform favored by European home automation professionals and enthusiasts — particularly those running KNX building systems, Modbus industrial sensors, or complex rule-based automations. With over 600 adapters for Philips Hue, Sonos, Z-Wave, Zigbee, Amazon Alexa, and Google Home, ioBroker ties together heterogeneous device ecosystems under a single rule engine. When the admin adapter process dies, the web UI goes dark and your entire automation logic stops responding. Vigilmon keeps watch over the ioBroker admin interface, REST API state endpoints, and critical adapter processes so failures surface immediately.

What You'll Set Up

• HTTP uptime monitor for the ioBroker admin web UI (port 8081)
• REST API health check via /api/v1/state/system.adapter.admin.0.alive for admin adapter status
• TCP port monitor for the ioBroker web server
• SSL certificate alerts for HTTPS-proxied ioBroker deployments
• Heartbeat monitoring for critical adapters (mqtt, zigbee, history) via the state API

Prerequisites

• ioBroker 5.0+ installed on Linux or in Docker
• Admin adapter running and accessible on port 8081
• A free Vigilmon account

Step 1: Monitor the ioBroker Admin Web UI

The ioBroker admin interface on port 8081 is your management dashboard. Add an HTTP monitor to confirm it's reachable:

1. Log in to vigilmon.online and click Add Monitor.
2. Set Type to HTTP / HTTPS.
3. Enter the URL: http://your-iobroker-host:8081/
4. Set Check interval to 1 minute.
5. Set Expected HTTP status to 200.
6. Click Save.

An unreachable admin UI means the admin adapter process has crashed or the ioBroker Node.js runtime has exited. This is your top-level indicator that the entire automation stack needs attention.

Step 2: Monitor the Admin Adapter State via REST API

ioBroker exposes a REST API that allows querying the internal object and state database. The /api/v1/state/system.adapter.admin.0.alive endpoint returns the live state of the admin adapter — whether it's running and healthy:

1. Click Add Monitor → HTTP / HTTPS.
2. Enter the URL: http://your-iobroker-host:8081/api/v1/state/system.adapter.admin.0.alive
3. Set Check interval to 1 minute.
4. Set Expected HTTP status to 200.
5. Under Response body check, enter "val":true to confirm the adapter is reporting alive.
6. Click Save.

A healthy response looks like:

{
  "val": true,
  "ack": true,
  "ts": 1704067200000,
  "q": 0,
  "from": "system.adapter.admin.0",
  "lc": 1704067200000
}

If val is false or the endpoint returns an error, the admin adapter has died even if the web server is still nominally accepting connections.

Step 3: Add a TCP Port Monitor

A TCP monitor verifies that the ioBroker web server is accepting connections at the network level:

1. Click Add Monitor → TCP Port.
2. Enter the host: your-iobroker-host
3. Set Port to 8081.
4. Set Check interval to 1 minute.
5. Click Save.

TCP monitoring catches scenarios where the Node.js process has entered an unresponsive state — the port is still bound but HTTP requests hang indefinitely without completing.

Step 4: SSL Certificate Alerts for Proxied Deployments

ioBroker is commonly placed behind an nginx reverse proxy with a Let's Encrypt certificate, especially when accessed remotely. Certificate expiry cuts off secure remote management.

1. Open the HTTP / HTTPS monitor you created in Step 1.
2. Update the URL to https://iobroker.yourdomain.com if using HTTPS.
3. Enable Monitor SSL certificate.
4. Set Alert when certificate expires in less than 21 days.
5. Click Save.

A minimal nginx reverse proxy config for ioBroker:

server {
    listen 443 ssl;
    server_name iobroker.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/iobroker.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/iobroker.yourdomain.com/privkey.pem;

    location / {
        proxy_pass http://localhost:8081;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

A 21-day alert window gives you time to diagnose Let's Encrypt renewal failures before losing secure remote access to your automation controller.

Step 5: Heartbeat Monitoring for Critical Adapters

ioBroker adapters run as separate Node.js processes. A crashed mqtt, zigbee, or history adapter won't bring down the admin UI — your automations silently break while the dashboard looks fine. Use Vigilmon's cron heartbeat to continuously verify that critical adapters are alive.

1. In Vigilmon, click Add Monitor → Cron Heartbeat.
2. Set the expected ping interval to 5 minutes.
3. Copy the heartbeat URL (e.g., https://vigilmon.online/heartbeat/abc123).

Create a heartbeat script that checks your critical adapters:

#!/bin/bash
# /usr/local/bin/iobroker-heartbeat.sh

IB_HOST="http://localhost:8081"
VIGILMON_URL="https://vigilmon.online/heartbeat/abc123"

# List of critical adapters to check
ADAPTERS=("mqtt.0" "zigbee.0" "history.0")

ALL_OK=true

for ADAPTER in "${ADAPTERS[@]}"; do
  STATE=$(curl -sf "$IB_HOST/api/v1/state/system.adapter.$ADAPTER.alive")

  if [ $? -ne 0 ]; then
    echo "Failed to reach ioBroker API for adapter $ADAPTER"
    ALL_OK=false
    break
  fi

  ALIVE=$(echo "$STATE" | grep -o '"val":true')
  if [ -z "$ALIVE" ]; then
    echo "Adapter $ADAPTER is NOT alive"
    ALL_OK=false
    break
  fi
done

if [ "$ALL_OK" = true ]; then
  curl -sf "$VIGILMON_URL" > /dev/null
  echo "ioBroker adapter heartbeat OK"
else
  echo "One or more adapters are down — not pinging Vigilmon"
  exit 1
fi

Schedule with cron:

crontab -e
# Add:
*/5 * * * * /usr/local/bin/iobroker-heartbeat.sh >> /var/log/iobroker-heartbeat.log 2>&1

Customize ADAPTERS to match the adapters critical to your home setup. If any adapter is down, the script withholds the Vigilmon ping and the heartbeat monitor raises an alert after 5 minutes.

Step 6: Configure Alert Channels

1. Go to Alert Channels in Vigilmon and add email, Slack, or a webhook.
2. On the web UI and state API monitors, set Consecutive failures before alert to 2 — ioBroker adapters can take 10–30 seconds to restart after a watchdog-initiated recovery.
3. On the heartbeat monitor, set the threshold to 1 missed ping — a missed heartbeat means an adapter is confirmed down.

Summary

| Monitor | Target | What It Catches | |---|---|---| | HTTP — Admin UI | http://host:8081/ | Admin process crash, web server down | | HTTP — State API | http://host:8081/api/v1/state/system.adapter.admin.0.alive | Admin adapter failure | | TCP Port | host:8081 | Web server not accepting connections | | SSL Certificate | https://iobroker.yourdomain.com | Let's Encrypt renewal failure | | Cron Heartbeat | Heartbeat URL | Critical adapter crash (mqtt, zigbee, history) |

ioBroker's adapter-per-process architecture means failures are often invisible — the UI stays green while automation logic silently breaks. With Vigilmon watching the admin interface, state API, and individual adapter health, you'll surface adapter crashes before your KNX scenes or MQTT automations stop firing.