Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Explain the limits of TrueNAS protection evidence

pulse-triage[bot]30a94c41861c
diff --git a/docs/TRUENAS.md b/docs/TRUENAS.md
index 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) before
testing 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 health
In **TrueNAS → Storage**, read the disk's **Health** reason and details, not
diff --git a/frontend-modern/public/docs/TRUENAS.md b/frontend-modern/public/docs/TRUENAS.md
index 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) before
testing 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 health
In **TrueNAS → Storage**, read the disk's **Health** reason and details, not
diff --git a/frontend-modern/src/features/docs/__tests__/truenasProtectionEvidenceDocs.test.ts b/frontend-modern/src/features/docs/__tests__/truenasProtectionEvidenceDocs.test.ts
new file mode 100644
index 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',
+ );
+ });
+});