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 PBS protection disagreements without changing backups

pulse-triage[bot]10322292ef66
diff --git a/docs/PBS.md b/docs/PBS.md
index 8f31f3cda4..43aabdbba6 100644
--- a/docs/PBS.md
+++ b/docs/PBS.md
@@ -302,6 +302,52 @@ private keys. If help is needed, provide only the HTTP status, relevant redacted
error and which expected reading is missing. Do not clear History or recreate a
working connection to make missing data look resolved.
+### Backups are visible but Coverage says Unprotected
+
+The **Backup health** strip and the backup list answer different questions.
+If they disagree, use **PBS's own backup and verification records** for the
+same guest while checking Pulse's assessment; do not assume either a failed
+backup or working protection from the strip alone.
+
+| Observation in Pulse | What it does not establish |
+| --- | --- |
+| **With PBS snapshots** or a matching backup row | That Pulse's protection assessment received the same subject-linked backup evidence. A similar name or guest ID alone is not identity proof. |
+| **Verified** on a PBS backup | That every backup is current, every covered disk is included, or the guest recovered after the backup. Verification is evidence about that backup, not a successful restore. |
+| **Protected**, **Attention**, **Unprotected** or **Unknown** | An independent check that backups are restorable. These are Pulse's assessment from the backup evidence it can read, not instructions to change backups. |
+
+Check one affected guest without changing its setup:
+
+1. Open **Proxmox → Backups → Coverage** and expand that guest. Read its
+ protection explanation and the PBS **Job**, **History** and **Access**
+ evidence. Access describes permissions; if provider evidence is absent,
+ record that rather than interpreting it as healthy. These are backup
+ evidence states, not the PBS host's CPU/metrics History chart.
+2. Compare the listed backup with the existing record in PBS: server,
+ datastore, namespace (including root), guest type/ID and backup time.
+ Independent PVE installations can reuse an ID; confirm the owning
+ installation too. A **guest snapshot** is not a PBS backup. Check the
+ existing backup task and verification result in PBS, not just the last
+ time Pulse refreshed.
+3. If the records still disagree, report the Pulse version, one guest's
+ protection explanation, PBS Job/History/Access values and the matching
+ backup's time and verification result. Use consistent placeholders for
+ private server, datastore, namespace and guest identities. Do not share
+ tokens, full API responses, HAR exports, or screenshots with secrets.
+
+Do not delete backups, clear History, change retention or freshness settings,
+recreate tokens/connections, restart or downgrade Pulse, or run a new backup,
+verification or restore just to clear the strip. Missing or contradictory
+Pulse evidence needs investigation, not a destructive diagnostic or an
+assumed freshness-policy cause. Use your established backup checks meanwhile.
+
+**An OK backup task or a Verified label does not prove the guest thawed.** If a
+backup left a guest unresponsive or frozen, follow [Backup safety](VM_DISK_MONITORING.md#backup-safety)
+and the platform's established recovery procedure, not this display check.
+Keep affected Pulse monitoring stopped until independent post-backup checks
+confirm thaw, fresh successful writes to every filesystem covered by the
+backup and workload liveness; restore only services and timers active before
+the pause. Monitoring and alerts are unavailable while Pulse is stopped.
+
### PBS is connected but History stays empty
Open **Proxmox → Backups → Backup Server → History**, not a datastore or the
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index 53acc5669a..53e2d37354 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -8831,3 +8831,20 @@ probe is prescribed. Independent thaw, every-covered-filesystem writes and
liveness remain the backup restoration boundary. The shipped mirror and
`backupSafetyHelp.test.ts` validate the rendered guidance and anchor; both new
controls reject the original parent guide. No runtime or wire contract changes.
+
+### PBS protection disagreement help (6 October 2026)
+
+The existing PBS guide separates visible/matched/verified backup artifacts from
+subject-linked protection assessment and independent restore or guest recovery
+proof. Its passive Coverage check uses the shipped Job, History and Access
+labels, existing PBS records and scoped redacted reporting. No task is induced,
+no identity/permission/retention setting is changed and no policy cause is
+assumed. Frozen/unresponsive guests retain independent post-backup thaw, writes
+on every covered filesystem, liveness and only-prior-active restoration with
+the monitoring/alert outage disclosed.
+
+`pbsProtectionHelp.test.ts` checks the production Markdown renderer, ordered
+passive steps, evidence distinctions, safety link/target, disclosure and exact
+shipped mirror. Exact-parent controls reject the old guide. This is safe help
+maintenance, not a collector/classifier repair, browser acceptance, native
+backup/recovery proof or published availability.
diff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.md
index 8f31f3cda4..43aabdbba6 100644
--- a/frontend-modern/public/docs/PBS.md
+++ b/frontend-modern/public/docs/PBS.md
@@ -302,6 +302,52 @@ private keys. If help is needed, provide only the HTTP status, relevant redacted
error and which expected reading is missing. Do not clear History or recreate a
working connection to make missing data look resolved.
+### Backups are visible but Coverage says Unprotected
+
+The **Backup health** strip and the backup list answer different questions.
+If they disagree, use **PBS's own backup and verification records** for the
+same guest while checking Pulse's assessment; do not assume either a failed
+backup or working protection from the strip alone.
+
+| Observation in Pulse | What it does not establish |
+| --- | --- |
+| **With PBS snapshots** or a matching backup row | That Pulse's protection assessment received the same subject-linked backup evidence. A similar name or guest ID alone is not identity proof. |
+| **Verified** on a PBS backup | That every backup is current, every covered disk is included, or the guest recovered after the backup. Verification is evidence about that backup, not a successful restore. |
+| **Protected**, **Attention**, **Unprotected** or **Unknown** | An independent check that backups are restorable. These are Pulse's assessment from the backup evidence it can read, not instructions to change backups. |
+
+Check one affected guest without changing its setup:
+
+1. Open **Proxmox → Backups → Coverage** and expand that guest. Read its
+ protection explanation and the PBS **Job**, **History** and **Access**
+ evidence. Access describes permissions; if provider evidence is absent,
+ record that rather than interpreting it as healthy. These are backup
+ evidence states, not the PBS host's CPU/metrics History chart.
+2. Compare the listed backup with the existing record in PBS: server,
+ datastore, namespace (including root), guest type/ID and backup time.
+ Independent PVE installations can reuse an ID; confirm the owning
+ installation too. A **guest snapshot** is not a PBS backup. Check the
+ existing backup task and verification result in PBS, not just the last
+ time Pulse refreshed.
+3. If the records still disagree, report the Pulse version, one guest's
+ protection explanation, PBS Job/History/Access values and the matching
+ backup's time and verification result. Use consistent placeholders for
+ private server, datastore, namespace and guest identities. Do not share
+ tokens, full API responses, HAR exports, or screenshots with secrets.
+
+Do not delete backups, clear History, change retention or freshness settings,
+recreate tokens/connections, restart or downgrade Pulse, or run a new backup,
+verification or restore just to clear the strip. Missing or contradictory
+Pulse evidence needs investigation, not a destructive diagnostic or an
+assumed freshness-policy cause. Use your established backup checks meanwhile.
+
+**An OK backup task or a Verified label does not prove the guest thawed.** If a
+backup left a guest unresponsive or frozen, follow [Backup safety](VM_DISK_MONITORING.md#backup-safety)
+and the platform's established recovery procedure, not this display check.
+Keep affected Pulse monitoring stopped until independent post-backup checks
+confirm thaw, fresh successful writes to every filesystem covered by the
+backup and workload liveness; restore only services and timers active before
+the pause. Monitoring and alerts are unavailable while Pulse is stopped.
+
### PBS is connected but History stays empty
Open **Proxmox → Backups → Backup Server → History**, not a datastore or the
diff --git a/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts
new file mode 100644
index 0000000000..51cedf74f6
--- /dev/null
+++ b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts
@@ -0,0 +1,77 @@
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it } from 'vitest';
+import { renderDocMarkdown } from '@/features/docs/docMarkdown';
+
+const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');
+const read = (file: string) => readFileSync(path.join(root, file), 'utf8');
+const guide = read('docs/PBS.md');
+const section = guide.split('### Backups are visible but Coverage says Unprotected')[1]?.split('\n### ')[0] ?? '';
+const render = (markdown: string, name: string) => {
+ const article = document.createElement('article');
+ article.innerHTML = renderDocMarkdown(markdown, name);
+ return article;
+};
+const article = () => render(section, 'PBS');
+const text = () => article().textContent?.replace(/\s+/g, ' ');
+
+describe('PBS protection disagreement help', () => {
+ it('ships the section and distinguishes matching, verification and assessment from recovery proof', () => {
+ expect(read('frontend-modern/public/docs/PBS.md')).toBe(guide);
+ expect(render(guide, 'PBS').querySelector('#backups-are-visible-but-coverage-says-unprotected')).not.toBeNull();
+ const rows = [...article().querySelectorAll('tbody tr')].map((row) => row.textContent);
+ expect(rows).toHaveLength(3);
+ expect(rows[0]).toContain('subject-linked backup evidence');
+ expect(rows[0]).toContain('not identity proof');
+ expect(rows[1]).toContain('not a successful restore');
+ expect(rows[1]).toContain('every covered disk');
+ expect(rows[2]).toContain('not instructions to change backups');
+ expect(text()).toContain("PBS's own backup and verification records");
+ expect(text()).toContain('do not assume either a failed backup or working protection');
+ });
+
+ it('uses existing Coverage evidence and source identity without an induced request', () => {
+ const steps = [...article().querySelectorAll('ol > li')].map((step) => step.textContent?.replace(/\s+/g, ' '));
+ expect(steps).toHaveLength(3);
+ expect(steps[0]).toContain('Proxmox → Backups → Coverage');
+ expect(steps[0]).toContain('Job, History and Access');
+ expect(steps[0]).toContain('provider evidence is absent');
+ expect(steps[0]).toContain('not the PBS host');
+ expect(steps[1]).toContain('server, datastore, namespace (including root), guest type/ID and backup time');
+ expect(steps[1]).toContain('confirm the owning installation');
+ expect(steps[1]).toContain('guest snapshot is not a PBS backup');
+ expect(steps[2]).toContain('protection explanation');
+ expect(article().querySelector('pre')).toBeNull();
+ const coverage = read('frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx');
+ expect(coverage).toContain('Job {evidenceQualityLabel(provider.jobState)}');
+ expect(coverage).toContain('History {evidenceQualityLabel(provider.historyCompleteness)}');
+ expect(coverage).toContain('Access {evidenceQualityLabel(provider.permissions)}');
+ });
+
+ it('prevents destructive diagnostics and an assumed freshness-policy cause', () => {
+ expect(text()).toContain('Do not delete backups, clear History, change retention or freshness settings');
+ expect(text()).toContain('recreate tokens/connections, restart or downgrade Pulse');
+ expect(text()).toContain('run a new backup, verification or restore just to clear the strip');
+ expect(text()).toContain('not a destructive diagnostic or an assumed freshness-policy cause');
+ expect(text()).toContain('Use your established backup checks meanwhile');
+ });
+
+ it('links the frozen-guest boundary and preserves every restoration prerequisite', () => {
+ const link = article().querySelector('a[href="/docs/VM_DISK_MONITORING#backup-safety"]');
+ expect(link?.textContent).toBe('Backup safety');
+ expect(render(read('docs/VM_DISK_MONITORING.md'), 'VM_DISK_MONITORING').querySelector('#backup-safety')).not.toBeNull();
+ expect(text()).toContain('An OK backup task or a Verified label does not prove the guest thawed');
+ expect(text()).toContain('not this display check');
+ expect(text()).toContain('independent post-backup checks confirm thaw');
+ expect(text()).toContain('fresh successful writes to every filesystem covered by the backup and workload liveness');
+ expect(text()).toContain('restore only services and timers active before the pause');
+ expect(text()).toContain('Monitoring and alerts are unavailable while Pulse is stopped');
+ });
+
+ it('limits public diagnostics to the selected evidence without credentials or broad exports', () => {
+ expect(text()).toContain('Use consistent placeholders for private server, datastore, namespace and guest identities');
+ expect(text()).toContain('Do not share tokens, full API responses, HAR exports, or screenshots with secrets');
+ expect(text()).toContain("one guest's protection explanation, PBS Job/History/Access values");
+ });
+});