Real-time monitoring dashboard for Proxmox VE, PBS, Docker, Kubernetes, TrueNAS and vSphere. Self-hosted, with alerts for failed backups, full disks, unhealthy containers and offline nodes.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain the limits of TrueNAS protection evidence
pulse-triage[bot]30a94c41861c
diff --git a/docs/TRUENAS.md b/docs/TRUENAS.mdindex b880b3e51e..e03a63a2cf 100644--- a/docs/TRUENAS.md+++ b/docs/TRUENAS.md@@ -72,6 +72,59 @@ Pulse has collected; an absent tab is not proof of successful collection.For missing or stale data, use the [polling checks](#stale-truenas-data) beforetesting the connection or restarting.+## Read TrueNAS protection evidence++Open **TrueNAS → Protection** and clear the search and outcome filter to+**All**. The **Healthy** filter selects successful events; it does not certify+that every dataset is protected. The event count is not a complete backup+inventory: collection is bounded to 500 snapshots and 200 replication tasks+per collection, and retained events can outlive their source artifact.++| Row kind | What it records | What to check separately |+|---|---|---|+| **Snapshot**, target **Local ZFS** | A snapshot observed on the source TrueNAS system | It is not an independent copy. Confirm the snapshot still exists and can survive the failure you need to recover from. |+| **Replication** | A task's reported last-run state and source/target details | A configured task, **Running** or **Unknown** is not a completed copy. Confirm the intended target and its existing received snapshot in TrueNAS. |++Expand the row, including on a phone, and compare it with the same existing+record in TrueNAS:++1. **Identify the source.** Compare **Host**, **Dataset**, **Full name** or+ **Snapshot**. For replication also compare **Task ID**, **Source datasets**,+ **Target dataset** and **Direction**. Similar dataset or task names on two+ appliances do not identify the same copy. A target dataset name or the+ API's remote mode alone does not establish a separate machine or failure+ domain; confirm the actual destination in TrueNAS.+2. **Read the outcome and times together.** **Started**, **Completed** and+ **Last snapshot** describe collected evidence, not a restore test.+ **Running** remains incomplete even if a timestamp is present. A successful+ snapshot observation does not establish successful replication.+ **Current timestamp limitation:** when TrueNAS supplies no snapshot creation+ time, Pulse can show the collection time as **Completed**. Do not use that+ displayed time alone to judge backup age or retention; confirm the native+ snapshot's creation time. Replication with no known last-run time is+ **Unknown**, not a newly completed copy.+3. **Check the destination without starting work.** Use the provider's existing+ received-snapshot and task records. Confirm the same source snapshot, target+ and successful transfer result. Missing **Verified**, **Size** or timestamp+ fields are unavailable evidence, not a failed verification or a zero-sized+ backup. Snapshot **Size** is reported used space, not the size of a complete+ independent backup or replication transfer.++A green TrueNAS connection does not prove that snapshot or replication reads+succeeded. If records are absent or disagree, keep the existing native evidence+and follow the [stale-data checks](#stale-truenas-data); do not assume an empty+or filtered list means no backups. Do not run a new snapshot, replication,+verification or restore, delete records, change retention or widen permissions+just to make the views agree. Keep full dataset paths, appliance names,+credentials and inventories private; report only the version, affected view,+time and a consistently aliased comparison.++For actual recovery, use TrueNAS's procedure and an isolated destination, not+the live dataset as a diagnostic target. See [what recovery evidence establishes](RECOVERY.md#what-the-evidence-means).+Neither a successful event nor a corrected display proves application recovery+or guest thaw. For an unresponsive guest or uncertain freeze/thaw, stop this+comparison and use [Backup safety](VM_DISK_MONITORING.md#backup-safety).+## Disk temperature and healthIn **TrueNAS → Storage**, read the disk's **Health** reason and details, notdiff --git a/frontend-modern/public/docs/TRUENAS.md b/frontend-modern/public/docs/TRUENAS.mdindex b880b3e51e..e03a63a2cf 100644--- a/frontend-modern/public/docs/TRUENAS.md+++ b/frontend-modern/public/docs/TRUENAS.md@@ -72,6 +72,59 @@ Pulse has collected; an absent tab is not proof of successful collection.For missing or stale data, use the [polling checks](#stale-truenas-data) beforetesting the connection or restarting.+## Read TrueNAS protection evidence++Open **TrueNAS → Protection** and clear the search and outcome filter to+**All**. The **Healthy** filter selects successful events; it does not certify+that every dataset is protected. The event count is not a complete backup+inventory: collection is bounded to 500 snapshots and 200 replication tasks+per collection, and retained events can outlive their source artifact.++| Row kind | What it records | What to check separately |+|---|---|---|+| **Snapshot**, target **Local ZFS** | A snapshot observed on the source TrueNAS system | It is not an independent copy. Confirm the snapshot still exists and can survive the failure you need to recover from. |+| **Replication** | A task's reported last-run state and source/target details | A configured task, **Running** or **Unknown** is not a completed copy. Confirm the intended target and its existing received snapshot in TrueNAS. |++Expand the row, including on a phone, and compare it with the same existing+record in TrueNAS:++1. **Identify the source.** Compare **Host**, **Dataset**, **Full name** or+ **Snapshot**. For replication also compare **Task ID**, **Source datasets**,+ **Target dataset** and **Direction**. Similar dataset or task names on two+ appliances do not identify the same copy. A target dataset name or the+ API's remote mode alone does not establish a separate machine or failure+ domain; confirm the actual destination in TrueNAS.+2. **Read the outcome and times together.** **Started**, **Completed** and+ **Last snapshot** describe collected evidence, not a restore test.+ **Running** remains incomplete even if a timestamp is present. A successful+ snapshot observation does not establish successful replication.+ **Current timestamp limitation:** when TrueNAS supplies no snapshot creation+ time, Pulse can show the collection time as **Completed**. Do not use that+ displayed time alone to judge backup age or retention; confirm the native+ snapshot's creation time. Replication with no known last-run time is+ **Unknown**, not a newly completed copy.+3. **Check the destination without starting work.** Use the provider's existing+ received-snapshot and task records. Confirm the same source snapshot, target+ and successful transfer result. Missing **Verified**, **Size** or timestamp+ fields are unavailable evidence, not a failed verification or a zero-sized+ backup. Snapshot **Size** is reported used space, not the size of a complete+ independent backup or replication transfer.++A green TrueNAS connection does not prove that snapshot or replication reads+succeeded. If records are absent or disagree, keep the existing native evidence+and follow the [stale-data checks](#stale-truenas-data); do not assume an empty+or filtered list means no backups. Do not run a new snapshot, replication,+verification or restore, delete records, change retention or widen permissions+just to make the views agree. Keep full dataset paths, appliance names,+credentials and inventories private; report only the version, affected view,+time and a consistently aliased comparison.++For actual recovery, use TrueNAS's procedure and an isolated destination, not+the live dataset as a diagnostic target. See [what recovery evidence establishes](RECOVERY.md#what-the-evidence-means).+Neither a successful event nor a corrected display proves application recovery+or guest thaw. For an unresponsive guest or uncertain freeze/thaw, stop this+comparison and use [Backup safety](VM_DISK_MONITORING.md#backup-safety).+## Disk temperature and healthIn **TrueNAS → Storage**, read the disk's **Health** reason and details, notdiff --git a/frontend-modern/src/features/docs/__tests__/truenasProtectionEvidenceDocs.test.ts b/frontend-modern/src/features/docs/__tests__/truenasProtectionEvidenceDocs.test.tsnew file mode 100644index 0000000000..b1f0b1a99f--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/truenasProtectionEvidenceDocs.test.ts@@ -0,0 +1,108 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { createGuideFixture } from './guideFixture';++const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');+const readGuide = (name: string) =>+ readFileSync(path.join(repoRoot, 'frontend-modern/public/docs', `${name}.md`), 'utf8');+const renderGuide = createGuideFixture((name) =>+ name === 'TRUENAS' && process.env.PULSE_TRUENAS_PROTECTION_INPUT+ ? readFileSync(process.env.PULSE_TRUENAS_PROTECTION_INPUT, 'utf8')+ : readGuide(name),+);++function protectionSection() {+ const article = renderGuide('TRUENAS');+ const heading = article.querySelector('#read-truenas-protection-evidence');+ expect(heading).not.toBeNull();+ const section = document.createElement('section');+ for (+ let node = heading!.nextElementSibling;+ node && node.tagName !== 'H2';+ node = node.nextElementSibling+ ) {+ section.appendChild(node.cloneNode(true));+ }+ return section;+}++const prose = (element: HTMLElement) => element.textContent!.replace(/\s+/g, ' ').trim();++describe('TrueNAS protection evidence help', () => {+ it('distinguishes observed snapshots and task state from an independent completed copy', () => {+ const section = protectionSection();+ const text = prose(section);+ expect(section.querySelectorAll('tbody tr')).toHaveLength(2);+ expect(text).toContain('The Healthy filter selects successful events');+ expect(text).toContain('does not certify that every dataset is protected');+ expect(text).toContain('It is not an independent copy');+ expect(text).toContain('Running or Unknown is not a completed copy');+ expect(text).toContain('remote mode alone does not establish a separate machine or failure domain');+ });++ it('keeps the bounded collection and timestamp limitations visible beside the comparison', () => {+ const text = prose(protectionSection());+ const mapper = readFileSync(+ path.join(repoRoot, 'internal/recovery/mapper/truenas/mapper.go'),+ 'utf8',+ );+ const snapshots = mapper.match(/maxTrueNASSnapshotsPerIngest\s*=\s*(\d+)/)![1];+ const replications = mapper.match(/maxTrueNASReplicationsPerIngest\s*=\s*(\d+)/)![1];+ expect(text).toContain(`${snapshots} snapshots and ${replications} replication tasks per collection`);+ expect(text).toContain('retained events can outlive their source artifact');+ expect(text).toContain('Pulse can show the collection time as Completed');+ expect(text).toContain("confirm the native snapshot's creation time");+ expect(text).toContain('Running remains incomplete even if a timestamp is present');+ expect(text).toContain('Replication with no known last-run time is Unknown');+ });++ it('uses current detail labels to compare the same source and destination without active work', () => {+ const section = protectionSection();+ const text = prose(section);+ expect(section.querySelectorAll('ol > li')).toHaveLength(3);+ for (const label of [+ 'Host',+ 'Dataset',+ 'Full name',+ 'Task ID',+ 'Source datasets',+ 'Target dataset',+ 'Direction',+ 'Last snapshot',+ ]) {+ expect([...section.querySelectorAll('strong')].map((node) => node.textContent)).toContain(label);+ }+ expect(text).toContain('existing received-snapshot and task records');+ expect(text).toContain('unavailable evidence, not a failed verification or a zero-sized backup');+ expect(text).toContain('Snapshot Size is reported used space');+ expect(text).toContain('does not prove that snapshot or replication reads succeeded');+ expect(text).toContain('Do not run a new snapshot, replication, verification or restore');+ expect(text).toContain('delete records, change retention or widen permissions');+ expect(text).toContain(+ 'Keep full dataset paths, appliance names, credentials and inventories private',+ );+ expect(section.querySelector('pre')).toBeNull();+ });++ it('ships the same guide and links to actual polling, recovery and guest-safety headings', () => {+ const article = renderGuide('TRUENAS');+ const section = protectionSection();+ expect(article.querySelector('#stale-truenas-data')).not.toBeNull();+ expect(section.querySelector('a[href="#stale-truenas-data"]')).not.toBeNull();+ for (const [doc, fragment] of [+ ['RECOVERY', 'what-the-evidence-means'],+ ['VM_DISK_MONITORING', 'backup-safety'],+ ]) {+ expect(section.querySelector(`a[href="/docs/${doc}#${fragment}"]`)).not.toBeNull();+ expect(renderGuide(doc).querySelector(`#${fragment}`)).not.toBeNull();+ }+ expect(readGuide('TRUENAS')).toBe(readFileSync(path.join(repoRoot, 'docs/TRUENAS.md'), 'utf8'));+ const text = prose(section);+ expect(text).toContain('an isolated destination, not the live dataset');+ expect(text).toContain(+ 'Neither a successful event nor a corrected display proves application recovery or guest thaw',+ );+ });+});