Pulse/docs/TRUENAS.md

TrueNAS Integration

Pulse v6 includes first-class monitoring for TrueNAS SCALE and TrueNAS CORE systems. TrueNAS data flows through the unified resource model, appearing alongside Proxmox, Docker, Kubernetes, and host agent data throughout the UI.

Quick Start

1. Go to Settings → TrueNAS.
2. Click Add Connection.
3. Enter the TrueNAS URL (e.g., https://truenas.local) and an API key.
4. Click Test Connection → Save.
5. Data appears within one polling cycle (~30 seconds).

Creating a TrueNAS API Key

On your TrueNAS system:

1. Navigate to Settings → API Keys (SCALE) or System → API Keys (CORE).
2. Click Add and create a new key.
3. Copy the key value and paste it into Pulse.

Tip: A read-only key is sufficient for monitoring. Pulse does not write to TrueNAS.

What Gets Monitored

Data	Unified Page	Details
System info (hostname, version, uptime)	Infrastructure	CPU, memory, health status
ZFS Pools	Storage	Total/used/free capacity, pool status (ONLINE/DEGRADED/FAULTED)
ZFS Datasets	Storage	Used/available space, mount status, read-only flag
Physical Disks	Storage	Model, serial, size, transport type, rotational flag
ZFS Snapshots	Recovery	Dataset, creation time, size, referenced data
Replication Tasks	Recovery	Source/target datasets, direction, last run status
TrueNAS Alerts	Alerts	Native TrueNAS alert messages and severity levels

Unified Resource Mapping

TrueNAS resources are mapped into the unified resource model:

• TrueNAS host → appears as a resource with source: truenas on the Infrastructure page.
• ZFS pools and datasets → appear on the Storage page.
• ZFS snapshots and replication → appear on the Recovery page as recovery points.
• TrueNAS alerts → surfaced on the Alerts page alongside Proxmox and other platform alerts.

Resources from TrueNAS can be filtered using the source filter on any page.

Multiple TrueNAS Systems

Add as many TrueNAS connections as needed. Each connection is polled independently. Resources from all connected systems are merged into the unified view.

Configuration

Environment Variables

Variable	Description	Default
PULSE_ENABLE_TRUENAS	Enable/disable TrueNAS integration	true

Storage

TrueNAS connection credentials are stored encrypted in truenas.enc in the Pulse data directory (/etc/pulse or /data).

API Reference

All endpoints require admin authentication.

Method	Endpoint	Description
GET	/api/truenas/connections	List all configured TrueNAS connections
POST	/api/truenas/connections	Add a new TrueNAS connection
DELETE	/api/truenas/connections/{id}	Remove a TrueNAS connection
POST	/api/truenas/connections/test	Test a connection before saving

Adding a connection (API)

curl -X POST http://localhost:7655/api/truenas/connections \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"nas-1","host":"https://truenas.local","api_key":"your-api-key"}'

Testing a connection (API)

curl -X POST http://localhost:7655/api/truenas/connections/test \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"nas-1","host":"https://truenas.local","api_key":"your-api-key"}'

Troubleshooting

"TrueNAS service unavailable"

• Check that the TrueNAS system is reachable from the Pulse server.
• Verify the URL includes the protocol (https://).
• Test connectivity manually:

  curl -sk -H "Authorization: Bearer <api-key>" https://<truenas-ip>/api/v2.0/system/info
  

No data appearing after adding connection

• Wait at least 30 seconds for the first poll cycle.
• Check Pulse logs for TrueNAS-related errors:

  journalctl -u pulse | grep -i truenas
  # or
  docker logs pulse | grep -i truenas
  

Stale TrueNAS data

• If TrueNAS data stops updating, the source status transitions to stale after ~120 seconds.
• Check TrueNAS connectivity and API key validity.
• Verify with the API:

  curl -H "Authorization: Bearer $TOKEN" http://localhost:7655/api/resources \
    | jq '.resources[] | select(.platformType == "truenas")'
  

Disabling TrueNAS integration

Set PULSE_ENABLE_TRUENAS=false and restart Pulse. Existing connection data is preserved but polling stops.

See Also

• Configuration Guide — environment variables and setup
• ZFS Monitoring — Proxmox-native ZFS pool monitoring
• Recovery — TrueNAS snapshots in the recovery view