System Monitoring Integrations

System monitoring integrations provide real-time visibility into your infrastructure, including virtualization hosts, storage systems, and server metrics.

Supported Systems

Virtualization

Proxmox - Full cluster monitoring

Storage Systems

TrueNAS, Unraid, OpenMediaVault

System Metrics

Glances, Dashdot

Networking

UniFi Controller, OPNsense

Proxmox

Monitor Proxmox Virtual Environment clusters with comprehensive health and resource tracking.

Configuration

url

string

required

Base URL of Proxmox (e.g., https://proxmox.local:8006)

username

string

required

Proxmox username (format: user@realm)

realm

string

required

Authentication realm (usually pam or pve)

tokenId

string

required

API token ID (format: token-name)

apiKey

string

required

API token secret

Creating an API Token

Open Datacenter

Permissions

Go to Permissions → API Tokens

Add Token

Click Add and select:

User: Your user account
Token ID: Choose a name (e.g., homarr)
Privilege Separation: Uncheck for full user permissions

Copy Credentials

Important: Save both the Token ID and Secret immediately!

Token Format: The full token ID will be username@realm!token-nameExample: homarr@pam!homarr

Available Features

Cluster Information

Complete cluster resource overview:Nodes:

CPU utilization and core count
Memory usage (used/total)
Storage usage (read/write metrics)
Network traffic (in/out)
Node status (online/offline)
High availability state
Uptime tracking

Virtual Machines (QEMU):

VM ID and name
Running/stopped status
Resource allocation and usage
CPU, memory, disk metrics
Network traffic
Host node assignment

Containers (LXC):

Container ID and name
Status and resource usage
Lightweight metrics
Node placement

Storage:

Storage pool status
Total and used space
Storage type/plugin
Shared storage detection
Availability status

API Method: getClusterInfoAsync()

Resource Mapping

The integration categorizes resources:

{
  nodes: NodeResource[],      // Physical Proxmox hosts
  vms: QemuResource[],         // Virtual machines
  lxcs: LxcResource[],         // LXC containers
  storages: StorageResource[]  // Storage pools
}

Each resource includes:

Unique identifier
Status and health
Resource utilization metrics
Network and disk I/O
Uptime information

Resource Types

Node
VM (QEMU)
Container (LXC)
Storage

{
  type: "node",
  id: "node/pve01",
  name: "pve01",
  status: "online",
  isRunning: true,
  cpu: {
    utilization: 0.15,  // 15%
    cores: 8
  },
  memory: {
    used: 16000000000,  // bytes
    total: 32000000000
  },
  storage: {
    used: 500000000000,
    total: 1000000000000,
    read: 1024000,   // bytes/sec
    write: 2048000
  },
  network: {
    in: 125000,      // bytes/sec
    out: 250000
  },
  uptime: 864000,    // seconds
  haState: null
}

{
  type: "qemu",
  vmId: 100,
  id: "qemu/100",
  name: "ubuntu-server",
  node: "pve01",
  status: "running",
  isRunning: true,
  cpu: {
    utilization: 0.25,
    cores: 4
  },
  memory: {
    used: 4000000000,
    total: 8000000000
  },
  storage: {
    used: 50000000000,
    total: 100000000000,
    read: 512000,
    write: 1024000
  },
  network: {
    in: 62500,
    out: 125000
  },
  uptime: 432000,
  haState: null
}

{
  type: "lxc",
  vmId: 200,
  id: "lxc/200",
  name: "docker-host",
  node: "pve02",
  status: "running",
  isRunning: true,
  cpu: {
    utilization: 0.10,
    cores: 2
  },
  memory: {
    used: 2000000000,
    total: 4000000000
  },
  // ... similar structure to VM
}

{
  type: "storage",
  id: "storage/pve01/local-lvm",
  name: "local-lvm",
  node: "pve01",
  status: "available",
  isRunning: true,
  storagePlugin: "lvmthin",
  total: 500000000000,
  used: 250000000000,
  isShared: false
}

Example Configuration

{
  "name": "Proxmox Cluster",
  "url": "https://proxmox.example.com:8006",
  "secrets": {
    "username": "homarr",
    "realm": "pam",
    "tokenId": "homarr",
    "apiKey": "your-token-secret-here"
  }
}

SSL Certificate: Proxmox uses self-signed certificates by default. Homarr must trust the certificate or have certificate validation disabled for testing.

TrueNAS

Monitor TrueNAS storage systems.

Configuration

url

string

required

TrueNAS URL (e.g., http://truenas.local)

apiKey

string

required

TrueNAS API key

Generating an API Key

Access the TrueNAS web interface

Account Settings

Click your username → API Keys

Add Key

Click Add and name it “Homarr”

Copy Key

Save the generated API key securely

Available Features

Pool status and capacity
Disk health monitoring
System resource usage
Service status
Alert monitoring

Example Configuration

{
  "name": "TrueNAS",
  "url": "http://192.168.1.100",
  "secrets": {
    "apiKey": "your-truenas-api-key"
  }
}

Unraid

Monitor Unraid servers.

Configuration

url

string

required

Unraid URL (e.g., http://unraid.local)

apiKey

string

required

Unraid API key or authentication token

Available Features

Array status and disk health
Parity check status
Cache pool monitoring
Docker container status
VM status
System temperature and fan speeds

Example Configuration

{
  "name": "Unraid Server",
  "url": "http://192.168.1.150",
  "secrets": {
    "apiKey": "your-unraid-api-key"
  }
}

OpenMediaVault

Monitor OpenMediaVault NAS systems.

Configuration

url

string

required

OMV URL (e.g., http://openmediavault.local)

apiKey

string

required

OMV API key

Available Features

Filesystem usage
Service status
System information
SMART disk data

Glances

Monitor system metrics via Glances API.

Configuration

url

string

required

Glances API URL (e.g., http://server.local:61208)

Setting Up Glances

Install Glances

pip install glances
# or
docker run -d -p 61208:61208 nicolargo/glances

Enable Web Server

glances -w

This starts Glances web server on port 61208

Configure Homarr

Use the Glances API URL in Homarr integration

Available Features

CPU usage and load averages
Memory and swap usage
Disk I/O and usage
Network traffic
Process list
Temperature sensors

Example Configuration

{
  "name": "Server Glances",
  "url": "http://192.168.1.200:61208",
  "secrets": {}
}

Dashdot

Modern system monitoring with a beautiful UI.

Configuration

url

string

required

Dashdot URL (e.g., http://dashdot.local:3001)

Setting Up Dashdot

docker run -d \
  --name dashdot \
  -p 3001:3001 \
  -v /:/mnt/host:ro \
  --privileged \
  mauricenino/dashdot

Available Features

Modern system overview
CPU, RAM, storage metrics
Network speed tests
Disk health
Service uptime

Comparison

System	Type	Metrics	Control	Complexity
Proxmox	Virtualization	⭐⭐⭐⭐⭐	✅	High
TrueNAS	Storage	⭐⭐⭐⭐	✅	Medium
Unraid	Storage	⭐⭐⭐⭐	✅	Medium
OpenMediaVault	Storage	⭐⭐⭐	✅	Low
Glances	Metrics	⭐⭐⭐⭐	❌	Low
Dashdot	Metrics	⭐⭐⭐	❌	Low

Networking Integrations

UniFi Controller

Monitor UniFi network equipment. Configuration:

URL: UniFi Controller address
Username and password for API access

Features:

Connected devices
Network throughput
AP and switch status
Client tracking

OPNsense

Monitor OPNsense firewall. Configuration:

URL: OPNsense address
API key and secret

Features:

Firewall interface statistics
CPU and memory usage
Gateway status
Active connections

Troubleshooting

Proxmox “Unauthorized” Error

Verify token format: user@realm!token-id
Check privilege separation setting
Ensure token has necessary permissions
Try creating new token

TrueNAS Connection Failed

Verify TrueNAS web interface is accessible
Check API key hasn’t expired
Ensure API access is enabled in TrueNAS settings

Test with curl:

curl -H "Authorization: Bearer API-KEY" http://truenas/api/v2.0/system/info

Glances Not Responding

Verify Glances is running: ps aux | grep glances
Check port 61208 is accessible
Test endpoint: curl http://server:61208/api/3/system
Review Glances logs

SSL Certificate Issues

Add self-signed cert to Homarr’s trust store
Or disable certificate validation (not recommended)
Use HTTP for local network testing

Best Practices

Separate API Users: Create dedicated API users/tokens for Homarr with minimal required permissions.

Monitor Critical Systems: Set up widgets for most important infrastructure
Alert Integration: Combine with notification systems for alerts
Regular Key Rotation: Rotate API keys periodically
Network Segmentation: Keep monitoring traffic on management VLAN
Dashboard Organization: Group related systems on same board

Next Steps

Health Widgets

Create system health monitoring widgets

Configure Boards

Organize systems across multiple dashboards

Troubleshooting

Common system monitoring issues

Get Started

Core Features

Configuration

Integrations

Guides

​Supported Systems

Virtualization

Storage Systems

System Metrics

Networking

​Proxmox

​Configuration

​Creating an API Token

​Available Features

​Resource Types

​Example Configuration

​TrueNAS

​Configuration

​Generating an API Key

​Available Features

​Example Configuration

​Unraid

​Configuration

​Available Features

​Example Configuration

​OpenMediaVault

​Configuration

​Available Features

​Glances

​Configuration

​Setting Up Glances

​Available Features

​Example Configuration

​Dashdot

​Configuration

​Setting Up Dashdot

​Available Features

​Comparison

​Networking Integrations

​UniFi Controller

​OPNsense

​Troubleshooting

​Proxmox “Unauthorized” Error

​TrueNAS Connection Failed

​Glances Not Responding

​SSL Certificate Issues

​Best Practices

​Next Steps

Health Widgets

Configure Boards

Troubleshooting

Build docs developers (and LLMs) love

Supported Systems

Proxmox

Configuration

Creating an API Token

Available Features

Resource Types

Example Configuration

TrueNAS

Configuration

Generating an API Key

Available Features

Example Configuration

Unraid

Configuration

Available Features

Example Configuration

OpenMediaVault

Configuration

Available Features

Glances

Configuration

Setting Up Glances

Available Features

Example Configuration

Dashdot

Configuration

Setting Up Dashdot

Available Features

Comparison

Networking Integrations

UniFi Controller

OPNsense

Troubleshooting

Proxmox “Unauthorized” Error

TrueNAS Connection Failed

Glances Not Responding

SSL Certificate Issues

Best Practices

Next Steps