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 PBS protection disagreements without changing backups
pulse-triage[bot]10322292ef66
diff --git a/docs/PBS.md b/docs/PBS.mdindex 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 redactederror and which expected reading is missing. Do not clear History or recreate aworking 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 emptyOpen **Proxmox → Backups → Backup Server → History**, not a datastore or thediff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.mdindex 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 andliveness remain the backup restoration boundary. The shipped mirror and`backupSafetyHelp.test.ts` validate the rendered guidance and anchor; both newcontrols 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.mdindex 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 redactederror and which expected reading is missing. Do not clear History or recreate aworking 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 emptyOpen **Proxmox → Backups → Backup Server → History**, not a datastore or thediff --git a/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.tsnew file mode 100644index 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");+ });+});