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 backup protection in plain words
rcourtman43c38253b675
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.mdindex 6eb8d0dd48..caa7456fdb 100644--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md@@ -7449,6 +7449,10 @@ presentation. The compact row remains actionable: plain-language rationale andprovider history/permission limitations live one disclosure deeper besidebounded restore evidence. A posture fetch failure must keep the evidenceinspectable and show unknown, never a locally inferred healthy fallback.+The table renders the server explanation verbatim and keeps its own fallbacks+(checking, not rated, unknown) and the snapshot-only age tooltip in the same+plain voice, without model terms such as canonical identity or provider+evidence.The bounded restore evidence keeps the newest point and the newest completedpoint of each source before filling with the newest overall, so a run of guestsnapshots or a running job cannot push the latest usable backup out of thediff --git a/docs/release-control/v6/internal/subsystems/storage-recovery.md b/docs/release-control/v6/internal/subsystems/storage-recovery.mdindex 890572cc5c..ed3f3e4803 100644--- a/docs/release-control/v6/internal/subsystems/storage-recovery.md+++ b/docs/release-control/v6/internal/subsystems/storage-recovery.md@@ -3808,6 +3808,16 @@ expected. Stale, failed, partial, or unverified evidence is attention;unprotected requires complete evidence of no qualifying backup; unavailableidentity, history, collection, or permission evidence fails to unknown.Snapshots remain distinct and never prove independent recovery by themselves.+The posture `explanation` is user-facing copy (the Coverage row tooltip and+expansion render it verbatim), so it is written in plain words rather than the+model's vocabulary: "recent backup", "full backup history", "one of its backup+sources has reported a failure", "verification is missing or overdue", and+the stale case names the policy window ("the newest confirmed backup is older+than 7 days") through `formatPostureWindow`, which never rounds a sub-hour or+fractional window up. Copy only claims a backup exists on branches that have+one. Terms such as+"subject-linked", "provider history" and "freshness window" stay in code and+contracts, not in the explanation.The per-tenant recovery store persists provider observations and a materializedposture index, refreshes it after writes, reconciliation, migration, identitydiff --git a/docs/release-control/v6/internal/subsystems/unified-resources.md b/docs/release-control/v6/internal/subsystems/unified-resources.mdindex 0a8439f2df..50115e23f5 100644--- a/docs/release-control/v6/internal/subsystems/unified-resources.md+++ b/docs/release-control/v6/internal/subsystems/unified-resources.md@@ -3312,7 +3312,10 @@ metadata.### Protection posture identity consumer`ProxmoxCoverageTable` remains a unified-resource identity consumer while-storage/recovery owns protection truth. Dropping the per-source age columns+storage/recovery owns protection truth. Its explanation copy for rows without a+canonical workload identity says so in user terms ("does not match a guest+Pulse currently monitors, so it is not rated"); the identity rule itself is+unchanged. Dropping the per-source age columnsfrom its rows changes no identity input: rows still key posture by the exactcanonical `Resource.id`. Live VM/LXC rows carry the exactcanonical `Resource.id` into one bounded posture batch; the table must not parsediff --git a/frontend-modern/browser-tests/composed-backups.cjs b/frontend-modern/browser-tests/composed-backups.cjsindex fd000eb8e1..e122af5292 100644--- a/frontend-modern/browser-tests/composed-backups.cjs+++ b/frontend-modern/browser-tests/composed-backups.cjs@@ -226,7 +226,7 @@ const { chromium, webkit } = require('playwright');await scopedAge.getByText('None', { exact: true }).waitFor();assert.ok((await scopedAge.locator('span[title]').getAttribute('title')).includes(- 'Guest snapshots alone do not prove independent recovery.',+ 'A snapshot is not a separate backup, so it does not count.',),);checks.push(diff --git a/frontend-modern/browser-verification/35a436c1be2a9bb6.json b/frontend-modern/browser-verification/35a436c1be2a9bb6.jsonnew file mode 100644index 0000000000..317ed3e74d--- /dev/null+++ b/frontend-modern/browser-verification/35a436c1be2a9bb6.json@@ -0,0 +1,36 @@+{+ "version": 1,+ "base_sha": "a82a8e04747263f5c49083f4c537e03040ba3c62",+ "verified_at": "2026-10-05T04:01:52Z",+ "result": "passed",+ "changed_paths": [+ "frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx",+ "frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts"+ ],+ "content_sha256": {+ "frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx": "ffdd41704d33d02194119521d60f2cfcfa1b2a10f069e95e80eaacee7f63d40f",+ "frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts": "9073910e7ccb6806424e3a324424942afef939d102fc40e94db8323100dd78a6"+ },+ "routes": [+ "/proxmox/backups/coverage"+ ],+ "viewports": [+ {+ "width": 1440,+ "height": 1000+ },+ {+ "width": 390,+ "height": 844+ }+ ],+ "states": [+ "Coverage rows on a rebuilt backend: protected, attention (failed source, stale beyond 7 days), unprotected (no backup, snapshots only), unknown and not-evaluated explanations all read in plain words",+ "Failed-source guest expansion: Needs attention: A backup exists, but one of its backup sources has reported a failure.",+ "Snapshot-only age tooltip: No PBS snapshot or PVE backup file. A snapshot is not a separate backup, so it does not count."+ ],+ "interactions": [+ "Read every posture tooltip on the coverage table",+ "Expanded the failed-source guest row"+ ]+}diff --git a/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx b/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsxindex 6fd43f852a..34233d7e81 100644--- a/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx+++ b/frontend-modern/src/features/proxmox/ProxmoxCoverageTable.tsx@@ -53,7 +53,7 @@ const COVERAGE_EMPTY_LABEL = 'None';const COVERAGE_NO_BACKUP_TITLE = 'No PBS snapshot or PVE backup file';// Matches the posture engine's own wording for a snapshot-only subject.const COVERAGE_SNAPSHOT_ONLY_TITLE =- 'No PBS snapshot or PVE backup file. Guest snapshots alone do not prove independent recovery.';+ 'No PBS snapshot or PVE backup file. A snapshot is not a separate backup, so it does not count.';function CoverageAgeFallback(props: { unknown?: boolean; emptyTitle: string; compact?: boolean }) {const title = () =>@@ -129,11 +129,11 @@ const evidenceQualityLabel = (value: string): string => {const postureExplanation = (row: WorkloadCoverageRow): string => {if (row.protectionPosture?.explanation) return row.protectionPosture.explanation;- if (row.posture === 'checking') return 'Pulse is checking provider protection evidence.';+ if (row.posture === 'checking') return "Pulse is checking this guest's backups.";if (row.posture === 'not-evaluated') {- return 'This backup target has no current canonical workload identity, so Pulse does not evaluate workload protection for it.';+ return 'This backup does not match a guest Pulse currently monitors, so it is not rated.';}- return 'Pulse does not have enough provider evidence to determine protection.';+ return 'Pulse cannot tell yet whether this guest is backed up.';};// "Workload coverage" table: one row per workload answering "does this have adiff --git a/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx b/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsxindex e9b9490ce0..a051faf0f4 100644--- a/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx+++ b/frontend-modern/src/features/proxmox/__tests__/ProxmoxCoverageTable.test.tsx@@ -225,4 +225,37 @@ describe('ProxmoxCoverageTable column visibility', () => {expect(empty(title)).toHaveTextContent(/^None$/);}});++ it('explains snapshot-only and unrated rows in plain words', () => {+ render(() => (+ <ProxmoxCoverageTable+ rows={[+ { ...row, key: 'snapshot-only', snapshotCount: 2 },+ { ...row, key: 'unrated', posture: 'not-evaluated', protectionPosture: undefined },+ ]}+ hasAnyRows+ emptyIcon={<span />}+ emptyTitle=""+ emptyDescription=""+ sortKey={(() => 'posture') as Accessor<CoverageSortKey>}+ sortDirection={() => 'asc'}+ onSort={() => {}}+ expandedKeys={new Set<string>()}+ onToggleExpand={() => {}}+ showTaskColumn={true}+ layoutWidth={() => 1_200}+ />+ ));++ const titles = [...document.querySelectorAll('td span[title]')].map((span) =>+ span.getAttribute('title'),+ );+ expect(titles).toContain(+ 'No PBS snapshot or PVE backup file. A snapshot is not a separate backup, so it does not count.',+ );+ expect(titles).toContain(+ 'This backup does not match a guest Pulse currently monitors, so it is not rated.',+ );+ expect(titles.join(' ')).not.toMatch(/canonical|provider evidence|independent recovery/);+ });});diff --git a/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts b/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.tsindex d75fe771e2..7c52f4d144 100644--- a/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts+++ b/frontend-modern/src/features/proxmox/proxmoxBackupRecoveryModel.ts@@ -149,7 +149,7 @@ export function getRecoveryAgeBand(// A guest snapshot shares the guest's storage, so it is listed as restore// evidence but never counted as a backup. Mirrors the server posture rule that-// "snapshots alone do not prove independent recovery".+// "a snapshot is not a separate backup, so it does not count".export function isBackupArtifact(artifact: RecoverableArtifact): boolean {return artifact.sourceKind !== 'snapshot';}diff --git a/internal/recovery/posture.go b/internal/recovery/posture.goindex 89abfa20cc..5065c6528b 100644--- a/internal/recovery/posture.go+++ b/internal/recovery/posture.go@@ -390,7 +390,7 @@ func DeriveProtectionPostureAt(ProviderStates: []ProtectionProviderState{},RepositoryResourceIDs: []string{},EvidenceIDs: []string{},- Explanation: "Pulse has no complete provider history linked to this resource, so protection is unknown.",+ Explanation: "Pulse has no readable backup history for this resource, so it cannot say whether it is protected.",EvaluatedAt: now,}@@ -561,37 +561,41 @@ func DeriveProtectionPostureAt((!stateVerificationExpected || posture.Verification == ProtectionVerificationVerified):posture.State = ProtectionStateProtectedif posture.Verification == ProtectionVerificationVerified {- posture.Explanation = "A current subject-linked backup is available and has recent verification evidence."+ posture.Explanation = "A recent backup is available and it was verified recently."} else {- posture.Explanation = "A current subject-linked backup is available from complete provider history."+ posture.Explanation = "A recent backup is available, and Pulse can see the full backup history."}if hasUnknownBlock {- posture.Explanation += " Another linked provider has unavailable history, but it does not invalidate the confirmed recovery point."+ posture.Explanation += " Another backup source could not be read, but that does not change this backup."}case hasSupportedQualifyingSuccess:posture.State = ProtectionStateAttentionswitch {case hasInvalidatingFailure:- posture.Explanation = "A backup exists, but a newer provider failure needs attention before Pulse can call this resource protected."+ posture.Explanation = "A backup exists, but one of its backup sources has reported a failure."case posture.Freshness == ProtectionFreshnessStale:- posture.Explanation = "The strongest subject-linked backup is older than the configured freshness window."+ posture.Explanation = fmt.Sprintf("The newest confirmed backup is older than %s.", formatPostureWindow(policy.FreshnessWindow))case stateVerificationExpected && posture.Verification != ProtectionVerificationVerified:- posture.Explanation = "A current backup exists, but its verification evidence is missing or stale."+ posture.Explanation = "A recent backup exists, but its verification is missing or overdue."default:- posture.Explanation = "Recovery evidence exists, but provider history or permissions are incomplete."+ posture.Explanation = "A backup exists, but Pulse can see only part of the backup history or cannot read all of it."}case hasUnknownBlock:posture.State = ProtectionStateUnknown- posture.Explanation = "Provider history or permissions are unavailable, so Pulse cannot make a stronger protection claim."+ posture.Explanation = "Pulse cannot read the backup history (it is unavailable or Pulse lacks permission), so it cannot say whether this is protected."case hasQualifyingSuccess || hasPartial:posture.State = ProtectionStateAttention- posture.Explanation = "Recovery evidence exists, but provider history or permissions are incomplete."+ if hasQualifyingSuccess {+ posture.Explanation = "A backup exists, but Pulse can see only part of the backup history or cannot read all of it."+ } else {+ posture.Explanation = "Pulse can see only part of the backup history, so it cannot confirm a backup."+ }case hasCompleteHistory:posture.State = ProtectionStateUnprotectedif hasSnapshotsOnly {- posture.Explanation = "Provider history is complete, but only snapshots are present; snapshots alone do not prove independent recovery."+ posture.Explanation = "Only snapshots were found. A snapshot is not a separate backup, so it does not count."} else {- posture.Explanation = "Provider history is complete, but no qualifying subject-linked backup exists."+ posture.Explanation = "Pulse can see the full backup history and found no backup for this resource."}default:posture.State = ProtectionStateUnknown@@ -684,3 +688,26 @@ func validProtectionPermissions(value operationaltrust.EvidencePermissions) boolreturn false}}++// formatPostureWindow renders the freshness window the way the explanation+// reads it: whole days, then whole hours, otherwise minutes, so a sub-hour or+// fractional window is never rounded into a claim it did not make.+func formatPostureWindow(window time.Duration) string {+ plural := func(n int, unit string) string {+ if n == 1 {+ return fmt.Sprintf("1 %s", unit)+ }+ return fmt.Sprintf("%d %ss", n, unit)+ }+ switch {+ case window >= 24*time.Hour && window%(24*time.Hour) == 0:+ return plural(int(window/(24*time.Hour)), "day")+ case window >= time.Hour && window%time.Hour == 0:+ return plural(int(window/time.Hour), "hour")+ case window > 0:+ minutes := int((window + time.Minute - 1) / time.Minute)+ return plural(minutes, "minute")+ default:+ return "0 minutes"+ }+}diff --git a/internal/recovery/posture_test.go b/internal/recovery/posture_test.goindex 103f0ad17a..9bf2041b78 100644--- a/internal/recovery/posture_test.go+++ b/internal/recovery/posture_test.go@@ -55,7 +55,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessCurrent,wantVerify: ProtectionVerificationVerified,wantCoverage: ProtectionCoverageComplete,- wantText: "current subject-linked backup",+ wantText: "A recent backup is available",},{name: "stale success needs attention",@@ -66,7 +66,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessStale,wantVerify: ProtectionVerificationStale,wantCoverage: ProtectionCoverageComplete,- wantText: "older than",+ wantText: "newest confirmed backup is older than 7 days",},{name: "missing expected verification needs attention",@@ -79,7 +79,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessCurrent,wantVerify: ProtectionVerificationUnverified,wantCoverage: ProtectionCoverageComplete,- wantText: "verification evidence",+ wantText: "verification is missing or overdue",},{name: "newer provider failure invalidates protected claim",@@ -94,7 +94,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessCurrent,wantVerify: ProtectionVerificationVerified,wantCoverage: ProtectionCoverageComplete,- wantText: "newer provider failure",+ wantText: "one of its backup sources has reported a failure",},{name: "complete snapshot-only history is unprotected",@@ -114,7 +114,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessUnknown,wantVerify: ProtectionVerificationUnknown,wantCoverage: ProtectionCoverageNone,- wantText: "snapshots alone",+ wantText: "A snapshot is not a separate backup",},{name: "partial provider history is attention when a backup exists",@@ -128,7 +128,21 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessCurrent,wantVerify: ProtectionVerificationVerified,wantCoverage: ProtectionCoveragePartial,- wantText: "incomplete",+ wantText: "only part of the backup history",+ },+ {+ name: "partial history without any backup does not claim one exists",+ summaries: func() []ProtectionProviderSummary {+ summary := protectionTestSummary(now, nil)+ summary.HistoryCompleteness = ProtectionHistoryPartial+ summary.BackupPointCount = 0+ return []ProtectionProviderSummary{summary}+ }(),+ wantState: ProtectionStateAttention,+ wantFresh: ProtectionFreshnessUnknown,+ wantVerify: ProtectionVerificationUnknown,+ wantCoverage: ProtectionCoveragePartial,+ wantText: "cannot confirm a backup",},{name: "permission denied is unknown",@@ -142,7 +156,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessCurrent,wantVerify: ProtectionVerificationVerified,wantCoverage: ProtectionCoverageUnknown,- wantText: "permissions are unavailable",+ wantText: "cannot read the backup history",},{name: "confirmed PBS recovery is not invalidated by an unknown legacy provider",@@ -166,7 +180,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessCurrent,wantVerify: ProtectionVerificationVerified,wantCoverage: ProtectionCoverageUnknown,- wantText: "does not invalidate",+ wantText: "does not change this backup",},{name: "no provider evidence is unknown",@@ -175,7 +189,7 @@ func TestDeriveProtectionPostureTruthTable(t *testing.T) {wantFresh: ProtectionFreshnessUnknown,wantVerify: ProtectionVerificationUnknown,wantCoverage: ProtectionCoverageUnknown,- wantText: "no complete provider history",+ wantText: "no readable backup history",},}@@ -338,7 +352,7 @@ func TestBuildProtectionPostureDoesNotTreatSuccessfulTaskAsAvailableBackup(t *teif got.LastSuccessfulPointAt != nil {t.Fatalf("last successful point = %v, want nil for task-only evidence", got.LastSuccessfulPointAt)}- if !strings.Contains(got.Explanation, "no qualifying subject-linked backup") {+ if !strings.Contains(got.Explanation, "found no backup") {t.Fatalf("explanation = %q, want no qualifying backup", got.Explanation)}}@@ -436,3 +450,23 @@ func TestDeriveProtectionPostureFailsClosedToDefaultPolicy(t *testing.T) {t.Fatalf("freshness = %q, want current after default-policy fallback", posture.Freshness)}}++func TestFormatPostureWindowReadsAsDaysOrHours(t *testing.T) {+ for _, tc := range []struct {+ window time.Duration+ want string+ }{+ {7 * 24 * time.Hour, "7 days"},+ {24 * time.Hour, "1 day"},+ {36 * time.Hour, "36 hours"},+ {time.Hour, "1 hour"},+ {30 * time.Minute, "30 minutes"},+ {90 * time.Minute, "90 minutes"},+ {time.Minute, "1 minute"},+ {0, "0 minutes"},+ } {+ if got := formatPostureWindow(tc.window); got != tc.want {+ t.Fatalf("formatPostureWindow(%s) = %q, want %q", tc.window, got, tc.want)+ }+ }+}