TrueNAS

The TrueNAS adapter uses TrueNAS’s WebSocket JSON-RPC transport (TLS mandatory). This transport replaces the REST v2.0 API that was removed in TrueNAS SCALE 25.x/26.0. FreeSDN connects via the WS endpoint, polls pool, disk, and alert state on a configurable interval (default: every 5 minutes), and surfaces storage status in the unified dashboard.

Caution

The TrueNAS adapter is the Storage module participant. It does not mount HTTP routes (no /api/v1/storage/ prefix). Storage health is surfaced through the dashboard and Fabric event bus. Staged blob writes are available to the backup and automation modules, not to end-user API callers directly.

What works

Feature	Details
ZFS pool health	Online / degraded / faulted / unknown; RAIDZ1/2/3 + mirror topology
Disk temperatures	Per-disk temperature readings with threshold alerting
Alerts	Active TrueNAS alert list (severity, message, klass) - dismissed alerts are filtered out at the adapter layer
Redundancy status	Vdev status and hot-spare availability
Scrub status	In-progress and last-completed scrub results
Health rollup	Aggregate OK/WARNING/CRITICAL rolled up to the dashboard
Staged blob writes	Write backup archives and config blobs to TrueNAS datasets via staging

Transport: WebSocket JSON-RPC

TrueNAS SCALE 25.04+ (Fangtooth) and 26.0 expose a JSON-RPC 2.0 WebSocket endpoint at:

wss://<nas-host>/api/current

All communication is JSON-RPC over this WebSocket. TLS is mandatory - FreeSDN auto-revokes the API key if a ws:// (plaintext) connection is attempted. You cannot disable TLS enforcement for TrueNAS connections.

Note

TrueNAS CORE 13.x and SCALE 22.12-24.10 do not use the WebSocket transport. The adapter automatically falls back to the REST v2.0 API at /api/v2.0/ for those versions. SCALE 25.04 deprecated REST v2.0, and 25.10/26.0 removed it entirely - the WebSocket endpoint is the only supported surface on those builds.

The adapter authenticates with an API key (preferred) or username/password. It opens a connection, reads health data, and closes the connection per polling cycle. There is no persistent connection and no reconnect/backoff loop - each polling pass is a discrete connect → authenticate → read → disconnect sequence.

Caution

TrueNAS ships with a self-signed certificate. Either import a proper TLS certificate in TrueNAS (System → Certificates), or install your CA bundle into the backend container’s OS trust store (e.g. update-ca-certificates) and set SSL_CERT_FILE to the bundle path, then re-register the controller with Verify SSL = true. An untrusted certificate will cause connection refusal.

Note

REQUESTS_CA_BUNDLE is a requests-library env var and has no effect here. The REST client uses httpx (reads SSL_CERT_FILE when trust_env=True). The WebSocket client builds its own ssl.SSLContext directly and does not read any CA-bundle env var - the CA must be in the OS trust store.

:::

Prerequisites

• TrueNAS CORE 13.x or TrueNAS SCALE 22.12 or later
• An API key created in TrueNAS (see below)
• HTTPS (port 443) accessible from the FreeSDN host to the TrueNAS system

Tip

TrueNAS SCALE removed REST v2.0 in version 25.x. If you are on SCALE 25.x or 26.x, you must use this WebSocket adapter - REST-based tools that relied on /api/v2.0/ will no longer work.

Creating an API key in TrueNAS

1. Log in to the TrueNAS web UI.
2. Top-right user menu → API Keys (SCALE) or System → API Keys (CORE).
3. Click Add, name it freesdn, leave the allowed hosts blank (or restrict to the FreeSDN host IP), and click Save.
4. Copy the generated key - it is shown only once.

Adding a TrueNAS system

# Add the TrueNAS system as a storage controller.
# Pass the API key as "password"  -  the adapter reads it from that field
# and presents it to TrueNAS as a Bearer token.
curl -X POST https://freesdn.example.com/api/v1/controllers \
  -H "Cookie: freesdn_access=<token>" \
  -H "X-CSRF-Token: <csrf>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "TrueNAS S4",
    "controller_type": "truenas",
    "host": "https://nas.example.com",
    "port": 443,
    "username": "",
    "password": "<truenas-api-key>",
    "site_id": "<site-uuid>"
  }'

FreeSDN opens a WebSocket connection per polling cycle (connect → authenticate → read → disconnect). Health data is visible on the dashboard after the first poll cycle completes (default interval: every 5 minutes).

Dashboard health rollup

The Storage dashboard card shows:

Indicator	Meaning
OK (green)	All pools online; no active alerts; all disks within temperature thresholds
WARNING (amber)	One or more pools degraded, or a disk is near temperature threshold, or a non-critical alert is active
CRITICAL (red)	One or more pools faulted, or a disk has failed, or a critical TrueNAS alert is active

The hot-disk alert fires when a disk temperature exceeds the per-vendor threshold (typically 55°C for spinning disks, 70°C for SSDs). Thresholds are configurable in the FreeSDN site settings.

Checking storage health via API

Health data is exposed through the Fabric catalog rather than dedicated REST routes. To query current pool status:

# Retrieve the full Fabric catalog (all modules  -  there is no server-side module filter)
curl https://freesdn.example.com/api/v1/fabric/catalog \
  -H "Cookie: freesdn_access=<token>"

The catalog endpoint returns every operation and event across all modules in a single response. There is no ?module= query parameter - FastAPI would silently ignore it and still return the full catalog. Filter storage-related entries client-side by checking operation.module == "storage" (or the equivalent key) in the returned JSON.

For dashboard-style summary data, the main dashboard endpoint aggregates storage health across all controllers:

curl https://freesdn.example.com/api/v1/analytics/dashboard/summary \
  -H "Cookie: freesdn_access=<token>"

Staged blob writes

The adapter supports writing backup archives and configuration blobs to TrueNAS datasets. This is used internally by:

• The Backup module (camera snapshots, log batches, and other artifact blobs staged to TrueNAS datasets via storage.store_blob)
• Fabric automation connections that route an artifact to TrueNAS

Blob writes go through the staging system - the write is recorded in FreeSDN’s pending-changes table and dispatched to TrueNAS only after an operator apply. This prevents accidental overwrites of backup datasets.

Tip

To route FreeSDN’s Configuration Backup archives to TrueNAS, configure a Fabric Connection with the storage module’s write_blob operation as the target action. See Fabric Connections for the how-to.

TrueNAS SCALE vs CORE

Behaviour	CORE 13.x	SCALE 23.x+
WebSocket endpoint	N/A (uses REST /api/v2.0/)	wss://<host>/api/current
REST v2.0	Available	Removed in 25.x
API key auth	Available	Available
Pool status method	pool.query	pool.query
Disk temp method	GET /api/v2.0/disk (REST, no temps)	disk.temperatures (WS, 25.04+ only)
Alert method	N/A - REST transport, not available	alert.list (WS, 25.04+ only)

Disk temperatures and active alerts are only available on SCALE 25.04+ via the WebSocket JSON-RPC transport. On CORE 13.x (and SCALE ≤24.10), the adapter falls back to the REST v2.0 client, which has no equivalent endpoint for either feature - the dashboard cards for those fields are silently empty for those boxes.

Gotchas

• ws:// is blocked - plaintext WebSocket connections auto-revoke the key. Always use https:// in the host field (the adapter derives wss:// from it automatically).
• RAIDZ3 + hot-disk alert - the adapter has been live-verified against a RAIDZ3 system with a hot-disk alert. The alert surfaced correctly in the dashboard as WARNING within one polling cycle.
• TrueNAS SCALE RDB format - TrueNAS SCALE uses a different RDB (boot pool) format than CORE. The adapter reads health state only; it does not interpret the boot pool. If the boot pool is degraded, the alert appears in the alert list but is not separately categorized.
• Session model - The adapter opens a WebSocket connection per polling cycle (connect, authenticate, poll, disconnect) rather than holding a persistent session. Idle-timeout is not a concern because the connection is closed after each operation. The websockets client is configured with ping_interval=None - no background pings are sent.

Adapter module

The TrueNAS adapter is registered under the Storage module (storage), not as a Network or Compute adapter. It participates in the Fabric catalog and the backup pipeline but does not expose standalone HTTP REST routes. There is no separate frontend page - storage health is visible on the main dashboard.