From ae3143a2ba27d5dea840fa28601a0988cff8f01f Mon Sep 17 00:00:00 2001
From: SandObserver <260779319+SandObserver@users.noreply.github.com>
Date: Thu, 22 Oct 2026 21:58:53 -0400
Subject: [PATCH] Docs: cover the TrueNAS WebSocket API and System Summary
 source

---
 src/content/docs/docs/security.md              |  2 +-
 src/content/docs/docs/widgets/disk-health.mdx  |  7 ++++---
 src/content/docs/docs/widgets/index.mdx        |  2 +-
 .../docs/docs/widgets/system-summary.mdx       | 18 +++++++++++++++---
 4 files changed, 21 insertions(+), 8 deletions(-)

diff --git a/src/content/docs/docs/security.md b/src/content/docs/docs/security.md
index 6bc1c3f..9ebf919 100644
--- a/src/content/docs/docs/security.md
+++ b/src/content/docs/docs/security.md
@@ -49,7 +49,7 @@ Secrets are stored in plain text in `apps.json` on the data volume. Protect that
 
 The server blocks outbound requests to private, loopback, link-local, carrier-grade NAT, multicast and reserved ranges, in IPv4 and IPv6. It resolves the host, checks the address, then pins the resolved IP so the connection cannot be re-pointed after the check.
 
-`localhost` is refused by name. A dotless hostname such as a Docker container name is resolved and pinned like any other name. It may point at a private address, but not at a loopback or link-local one. The host IP set in General is trusted. Only `http` and `https` URLs are fetched.
+`localhost` is refused by name. A dotless hostname such as a Docker container name is resolved and pinned like any other name. It may point at a private address, but not at a loopback or link-local one. The host IP set in General is trusted. Only `http` and `https` URLs are fetched. The WebSocket connection TrueNAS widgets use opens on the same URL and passes the same check.
 
 | Range | Why |
 | --- | --- |
diff --git a/src/content/docs/docs/widgets/disk-health.mdx b/src/content/docs/docs/widgets/disk-health.mdx
index 9b00cea..6dd5cad 100644
--- a/src/content/docs/docs/widgets/disk-health.mdx
+++ b/src/content/docs/docs/widgets/disk-health.mdx
@@ -37,10 +37,11 @@ Small holds four bays. Medium holds ten.
     kind: 'NAS operating system',
     needs: 'URL, API key',
     fields: [
-      ['TrueNAS URL', 'For example `truenas.local`.'],
-      ['TrueNAS API Key', 'Stored as a secret.'],
+      ['TrueNAS URL', 'For example `truenas.local`. An address without `https://` gets it. An `http://` address is refused, because TrueNAS revokes an API key sent over HTTP.'],
+      ['TrueNAS API Key', 'Stored as a secret. The `POOL_READ` role is enough.'],
+      ['Allow Self-Signed Certificate', 'Turn on for the certificate TrueNAS installs by default.'],
     ],
-    notes: ['TrueNAS 25.x only. Later versions do not have the REST API this widget reads. On a later version, run Scrutiny instead.'],
+    notes: ['Reads pool health. TrueNAS 25.04 and later answer on the WebSocket API. Older versions are read over the REST API.'],
     links: [{ label: 'truenas.com', href: 'https://www.truenas.com/' }],
   },
 ]} />
diff --git a/src/content/docs/docs/widgets/index.mdx b/src/content/docs/docs/widgets/index.mdx
index 3b3bf3f..5968db9 100644
--- a/src/content/docs/docs/widgets/index.mdx
+++ b/src/content/docs/docs/widgets/index.mdx
@@ -32,7 +32,7 @@ Widgets reorder in the same list as apps and folders. See [Apps and folders](/do
   { href: '/docs/widgets/dns/', name: 'DNS', text: 'Blocked and total queries.', value: 'AdGuard Home, Pi-hole, Technitium, NextDNS' },
   { href: '/docs/widgets/github/', name: 'GitHub', text: 'Pull requests or a contribution graph.', value: 'GitHub' },
   { href: '/docs/widgets/now-playing/', name: 'Now Playing', text: 'What is playing, with progress.', value: 'Plex, Jellyfin, Emby, Navidrome' },
-  { href: '/docs/widgets/system-summary/', name: 'System summary', text: 'CPU, memory, disk, temperature and network.', value: 'This machine, Glances, Beszel, Unraid' },
+  { href: '/docs/widgets/system-summary/', name: 'System summary', text: 'CPU, memory, disk, temperature and network.', value: 'This machine, Glances, Beszel, Unraid, TrueNAS' },
   { href: '/docs/widgets/weather/', name: 'Weather', text: 'Current conditions for one place.', value: 'Open-Meteo, OpenWeather' },
 ]} />
 
diff --git a/src/content/docs/docs/widgets/system-summary.mdx b/src/content/docs/docs/widgets/system-summary.mdx
index c9bb8d2..c921b2d 100644
--- a/src/content/docs/docs/widgets/system-summary.mdx
+++ b/src/content/docs/docs/widgets/system-summary.mdx
@@ -1,6 +1,6 @@
 ---
 title: System summary widget
-description: CPU, memory, disk, temperature and network stats from the host, Glances, Beszel or Unraid, on your Stackyard dashboard.
+description: CPU, memory, disk, temperature and network stats from the host, Glances, Beszel, Unraid or TrueNAS, on your Stackyard dashboard.
 ---
 
 import WidgetGroup from '../../../../components/WidgetGroup.astro';
@@ -66,6 +66,18 @@ Sizes: Small, Medium.
     notes: ['Unraid reports neither IO wait nor a process count.'],
     links: [{ label: 'unraid.net', href: 'https://unraid.net/' }],
   },
+  {
+    name: 'TrueNAS', icon: 'truenas-scale',
+    kind: 'NAS operating system',
+    needs: 'URL, API key',
+    fields: [
+      ['TrueNAS URL', 'For example `truenas.local`. An address without `https://` gets it. An `http://` address is refused, because TrueNAS revokes an API key sent over HTTP.'],
+      ['TrueNAS API Key', 'Stored as a secret. Create it for an account whose privilege has the `REPORTING_READ`, `POOL_READ` and `DATASET_READ` roles.'],
+      ['Allow Self-Signed Certificate', 'Turn on for the certificate TrueNAS installs by default.'],
+    ],
+    notes: ['TrueNAS 25.04 or later. TrueNAS reports neither IO wait nor a process count. A Disk slot reads a pool, or the first pool when empty. Memory leaves out the ZFS cache. Uptime needs the `READONLY_ADMIN` role, and is empty without it.'],
+    links: [{ label: 'truenas.com', href: 'https://www.truenas.com/' }],
+  },
 ]} />
 
 <SettingList title="Settings" items={[
@@ -91,7 +103,7 @@ The widget always shows three slots.
 <SettingList title="Settings for each slot" items={[
   { name: 'Resource', text: 'CPU, RAM, Temperature, Disk Mount, IO Wait or Processes.' },
   { name: 'Thermal Zone or Sensor', text: 'Temperature only. A thermal zone number for This Machine, 0 by default. A sensor picked from the loaded list for the other sources.' },
-  { name: 'First and second disk', text: 'Disk Mount only. Mount paths for This Machine and Glances, filesystem names for Beszel, share names for Unraid. The second is optional. An empty Unraid share reads the whole array.' },
+  { name: 'First and second disk', text: 'Disk Mount only. Mount paths for This Machine and Glances, filesystem names for Beszel, share names for Unraid, pool names for TrueNAS. The second is optional. An empty Unraid share reads the whole array. An empty TrueNAS pool reads the first pool.' },
   { name: 'Color', text: 'The slot colour. Defaults to blue.' },
 ]} />
 
@@ -101,7 +113,7 @@ Medium size only.
 
 <SettingList title="Network row settings" items={[
   { name: 'Show Network Row', text: 'Off by default.' },
-  { name: 'Mode', text: 'Speed shows the last speed test. Throughput shows live traffic on one interface. Uptime shows uptime.' },
+  { name: 'Mode', text: 'Speed shows the last speed test. Throughput shows live traffic on one interface, except for TrueNAS. Uptime shows uptime.' },
   { name: 'Interface', text: 'Throughput only, for Glances, Beszel and Unraid. Load the list, then pick one.' },
 ]} />