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

```bash
# 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

# Optional: Client ID (default: unraid-management-agent-<hostname>)
MQTT_CLIENT_ID=unraid-agent-tower
```

The broker allows one connection per client ID, so each server needs its own.
The default `unraid-management-agent` (or an empty value) is sent as
`unraid-management-agent-<hostname>`, which keeps several servers on one broker
apart without configuration. Any other value is used exactly as set. Old
MQTT 3.1 brokers accept at most 23 characters and reject longer IDs with
"identifier rejected"; set a short `MQTT_CLIENT_ID` for those. The agent logs
the client ID it connects with. The same
setting is `mqtt.client_id` in `config.yml` and `client_id` in the MQTT config
REST endpoint.

### Restart Service

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

### Verify Connection

Check logs for MQTT connection:

```bash
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**:

```json
{
  "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**:

```json
{
  "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**:

```json
[
  {
    "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`:

```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

```yaml
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

```yaml
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

```yaml
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

```json
[
  {
    "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**:

```json
{
  "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

```bash
# 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)

```bash
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:

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

```bash
# 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

```bash
# 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

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

### Authentication Errors

```bash
# 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)

```yaml
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`:

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

With authentication:

```conf
listener 1883
allow_anonymous false
password_file /mosquitto/config/passwd
```

Create password file:

```bash
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](home-assistant.md) - Complete HA setup
- [Grafana Integration](grafana.md) - Monitoring dashboards
- [REST API Reference](../api/rest-api.md) - Control via API
- [Configuration Guide](../guides/configuration.md) - Customize settings

---

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