MQTT Integration

Publish Unraid server events to MQTT brokers for IoT integration and Home Assistant automation.

Overview

The Unraid Management Agent can publish system events to MQTT brokers in real-time, enabling:

Home Assistant integration for smart home automation
IoT dashboards like Node-RED
Custom automation scripts
Multi-server monitoring from a central MQTT broker

Configuration

Enable MQTT

Edit /boot/config/plugins/unraid-management-agent/unraid-management-agent.cfg:

# Enable MQTT publishing
MQTT_ENABLED=true

# MQTT broker address (required)
MQTT_BROKER=tcp://192.168.1.100:1883

# Optional: Authentication
MQTT_USERNAME=unraid_agent
MQTT_PASSWORD=your_secure_password

# Optional: Topic prefix (default: unraid)
MQTT_TOPIC_PREFIX=homelab/unraid

Restart Service

/etc/rc.d/rc.unraid-management-agent restart

Verify Connection

Check logs for MQTT connection:

tail -f /var/log/unraid-management-agent.log | grep MQTT

You should see: MQTT client connected to tcp://...

MQTT Topics

The agent publishes to hierarchical topics under your configured prefix.

Topic Structure

<prefix>/system          # System metrics (CPU, RAM, temps)
<prefix>/array           # Array status and capacity
<prefix>/disks           # All disk information
<prefix>/shares          # User share list
<prefix>/containers      # Docker container status
<prefix>/vms             # Virtual machine status
<prefix>/ups             # UPS status (if configured)
<prefix>/gpu             # GPU metrics (if available)
<prefix>/network         # Network interface info
<prefix>/notifications   # System notifications (full list + counts)
<prefix>/notifications/event  # Per-notification event (fires once per new notification)

Message Format

All messages are published as JSON payloads with QoS 1 (at least once delivery).

System Topic Example

Topic: unraid/system

Payload:

{
  "hostname": "Tower",
  "version": "7.2.0",
  "agent_version": "2025.11.0",
  "uptime": 345600,
  "cpu_usage": 15.3,
  "cpu_temp": 45.5,
  "cpu_model": "Intel Core i7-9700K",
  "cpu_cores": 8,
  "cpu_threads": 8,
  "ram_used": 8589934592,
  "ram_total": 34359738368,
  "ram_usage": 25.0,
  "swap_total_bytes": 8589934592,
  "swap_used_bytes": 1073741824,
  "swap_free_bytes": 7516192768,
  "swap_usage_percent": 12.5,
  "swappiness": 60,
  "timestamp": "2025-01-20T10:30:00Z"
}

Swap fields are parsed from /proc/meminfo; swappiness reflects /proc/sys/vm/swappiness (-1 when unavailable). Byte fields are machine-readable; swap_usage_percent is the human-friendly view.

Array Topic Example

Topic: unraid/array

Payload:

{
  "state": "STARTED",
  "size": 12000000000000,
  "free": 8000000000000,
  "used_percent": 33.3,
  "num_disks": 6,
  "parity_valid": true,
  "parity_check_status": "idle",
  "timestamp": "2025-01-20T10:30:00Z"
}

Containers Topic Example

Topic: unraid/containers

Payload:

[
  {
    "id": "abc123def456",
    "name": "plex",
    "state": "running",
    "status": "Up 2 hours",
    "image": "plexinc/pms-docker:latest",
    "cpu_percent": 5.2,
    "memory_usage": 2147483648,
    "timestamp": "2025-01-20T10:30:00Z"
  }
]

Home Assistant Integration

MQTT Sensor Configuration

Add to your configuration.yaml:

mqtt:
  sensor:
    # CPU Usage
    - name: "Unraid CPU Usage"
      state_topic: "unraid/system"
      value_template: "{{ value_json.cpu_usage | round(1) }}"
      unit_of_measurement: "%"
      icon: mdi:cpu-64-bit

    # RAM Usage
    - name: "Unraid RAM Usage"
      state_topic: "unraid/system"
      value_template: "{{ value_json.ram_usage | round(1) }}"
      unit_of_measurement: "%"
      icon: mdi:memory

    # CPU Temperature
    - name: "Unraid CPU Temperature"
      state_topic: "unraid/system"
      value_template: "{{ value_json.cpu_temp | round(1) }}"
      unit_of_measurement: "°C"
      device_class: temperature

    # Array Status
    - name: "Unraid Array State"
      state_topic: "unraid/array"
      value_template: "{{ value_json.state }}"
      icon: mdi:server

    # Array Usage
    - name: "Unraid Array Usage"
      state_topic: "unraid/array"
      value_template: "{{ value_json.used_percent | round(1) }}"
      unit_of_measurement: "%"
      icon: mdi:harddisk

    # Parity Valid
    - name: "Unraid Parity Status"
      state_topic: "unraid/array"
      value_template: "{{ 'Valid' if value_json.parity_valid else 'Invalid' }}"
      icon: mdi:shield-check

Home Assistant Automation Examples

Alert on High CPU

automation:
  - alias: "Unraid High CPU Alert"
    trigger:
      - platform: numeric_state
        entity_id: sensor.unraid_cpu_usage
        above: 90
        for:
          minutes: 5
    action:
      - service: notify.mobile_app
        data:
          message: "Unraid CPU usage is {{ states('sensor.unraid_cpu_usage') }}%"
          title: "⚠️ Unraid Alert"

Alert on Parity Invalid

automation:
  - alias: "Unraid Parity Invalid Alert"
    trigger:
      - platform: state
        entity_id: sensor.unraid_parity_status
        to: "Invalid"
    action:
      - service: notify.mobile_app
        data:
          message: "Unraid array parity is INVALID!"
          title: "🚨 Unraid Critical Alert"

Container Stopped Alert

automation:
  - alias: "Plex Container Stopped"
    trigger:
      - platform: mqtt
        topic: "unraid/containers"
    condition:
      - condition: template
        value_template: >
          {% set containers = trigger.payload_json %}
          {% set plex = containers | selectattr('name', 'eq', 'plex') | list | first %}
          {{ plex.state != 'running' }}
    action:
      - service: notify.mobile_app
        data:
          message: "Plex container has stopped!"
          title: "⚠️ Unraid Container Alert"

Node-RED Integration

MQTT In Node

Configure an MQTT In node:

Server: Your MQTT broker
Topic: unraid/# (subscribe to all topics)
QoS: 1
Output: Parsed JSON object

Example Flow

[
  {
    "id": "mqtt_in",
    "type": "mqtt in",
    "topic": "unraid/system",
    "qos": "1",
    "broker": "mqtt_broker"
  },
  {
    "id": "cpu_check",
    "type": "function",
    "func": "if (msg.payload.cpu_usage > 80) {\n  msg.payload = {\n    title: 'High CPU Usage',\n    message: `CPU at ${msg.payload.cpu_usage}%`\n  };\n  return msg;\n}"
  },
  {
    "id": "notification",
    "type": "pushover",
    "title": "{{payload.title}}",
    "message": "{{payload.message}}"
  }
]

Notification Events (Home Assistant)

In addition to the notifications topic (full list + unread counts), the agent publishes a per-notification event to <prefix>/notifications/event and registers a Home Assistant MQTT event entity for it. One message is published the first time each notification ID is seen; the existing backlog is seeded silently on startup so an agent restart never replays old notifications. Event messages are not retained, so Home Assistant does not refire them on reconnect.

Topic: unraid/notifications/event

Payload:

{
  "event_type": "alert",
  "id": "notify_1737368400_0",
  "title": "Array Started",
  "subject": "Array Status",
  "description": "The array has been started",
  "importance": "alert",
  "type": "unread",
  "link": "/Dashboard",
  "timestamp": "2025-01-20T10:30:00Z",
  "formatted_timestamp": "2025-01-20 10:30:00"
}

event_type is one of alert, warning, or info (HA fires the event under this type). All notification details are carried as event attributes so automations have the full context. timestamp is machine-readable (RFC 3339); formatted_timestamp is the human-readable form.

Testing MQTT

Subscribe to All Topics

# Using mosquitto_sub
mosquitto_sub -h localhost -t "unraid/#" -v

# With authentication
mosquitto_sub -h localhost -u username -P password -t "unraid/#" -v

Publish Test Message (API)

curl -X POST http://localhost:8043/api/v1/mqtt/publish \
  -H "Content-Type: application/json" \
  -d '{
    "topic": "unraid/test",
    "payload": {"message": "test"},
    "retained": false
  }'

Advanced Configuration

TLS/SSL

For secure MQTT connections:

# Use ssl:// instead of tcp://
MQTT_BROKER=ssl://mqtt.example.com:8883

Note: TLS certificate validation is performed. Ensure valid certificates or configure your broker accordingly.

QoS and Retained Messages

QoS: Messages are published with QoS 1 (at least once delivery)
Retained: Messages are NOT retained by default (latest state only)

To enable retained messages for persistent state, this would require a code modification.

Custom Topic Prefix

Use hierarchical topics for multi-server setups:

# Server 1
MQTT_TOPIC_PREFIX=homelab/tower1

# Server 2
MQTT_TOPIC_PREFIX=homelab/tower2

Topics become:

homelab/tower1/system
homelab/tower2/system

Troubleshooting

Connection Failed

# Check logs
tail -f /var/log/unraid-management-agent.log | grep MQTT

# Test broker connectivity
mosquitto_sub -h BROKER_IP -p 1883 -t "test"

# Test with authentication
mosquitto_pub -h BROKER_IP -u username -P password -t "test" -m "hello"

No Messages Received

Verify MQTT is enabled in config
Check broker is running: ps aux | grep mosquitto
Verify topic subscription: mosquitto_sub -t "unraid/#" -v
Check firewall rules on broker

Authentication Errors

# Verify credentials
mosquitto_pub -h BROKER_IP -u username -P password -t "test" -m "test"

# Check broker logs
tail -f /var/log/mosquitto/mosquitto.log

MQTT Broker Setup

Mosquitto on Unraid (Docker)

version: "3"
services:
  mosquitto:
    image: eclipse-mosquitto:latest
    container_name: mosquitto
    restart: unless-stopped
    ports:
      - "1883:1883"
      - "9001:9001"
    volumes:
      - ./config:/mosquitto/config
      - ./data:/mosquitto/data
      - ./log:/mosquitto/log

Create config/mosquitto.conf:

listener 1883
allow_anonymous true
persistence true
persistence_location /mosquitto/data/
log_dest file /mosquitto/log/mosquitto.log

With authentication:

listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd

Create password file:

docker exec mosquitto mosquitto_passwd -c /mosquitto/config/passwd username

Performance Considerations

Message Rate

With default collection intervals:

Fast topics (5-10s): system, array, containers, vms
Moderate topics (30-60s): disks, shares, network
Total message rate: ~10-15 messages/minute

Bandwidth

Typical bandwidth usage:

Average message size: 200-500 bytes
Peak bandwidth: <1 KB/s
Daily data: <50 MB

Broker Load

Impact on MQTT broker:

CPU: Negligible
Memory: ~5-10 MB per client
Connections: 1 persistent connection

Next Steps

Home Assistant Integration - Complete HA setup
Grafana Integration - Monitoring dashboards
REST API Reference - Control via API
Configuration Guide - Customize settings

Last Updated: January 2026
MQTT Protocol Version: 3.1.1
Topics Published: 10+

FilesExpand file tree

mqtt.md

Latest commit

History

mqtt.md

File metadata and controls

MQTT Integration

Overview

Configuration

Enable MQTT

Restart Service

Verify Connection

MQTT Topics

Topic Structure

Message Format

System Topic Example

Array Topic Example

Containers Topic Example

Home Assistant Integration

MQTT Sensor Configuration

Home Assistant Automation Examples

Alert on High CPU

Alert on Parity Invalid

Container Stopped Alert

Node-RED Integration

MQTT In Node

Example Flow

Notification Events (Home Assistant)

Testing MQTT

Subscribe to All Topics

Publish Test Message (API)

Advanced Configuration

TLS/SSL

QoS and Retained Messages

Custom Topic Prefix

Troubleshooting

Connection Failed

No Messages Received

Authentication Errors

MQTT Broker Setup

Mosquitto on Unraid (Docker)

Performance Considerations

Message Rate

Bandwidth

Broker Load

Next Steps