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
Clarify PBS verification and protection evidence in help
pulse-triage[bot]3573abbf0eca
diff --git a/docs/PBS.md b/docs/PBS.mdindex bfb61548c9..72f2318adf 100644--- a/docs/PBS.md+++ b/docs/PBS.md@@ -347,7 +347,8 @@ backup or working protection from the strip alone.| --- | --- || **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. |+| **Protected** in a restore point's **State** | That this point is verified. This displays the backup's protected flag before its verification state; it is not the workload's protection assessment. |+| **Protected**, **Attention**, **Unprotected** or **Unknown** on the workload | 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:@@ -359,14 +360,27 @@ Check one affected guest without changing its setup: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.+ installation too. Under **Restore evidence**, choose the newest point whose+ **Source** is **PBS**, and read its **Created** time and **State**. Hover the+ Created age for its absolute timestamp; if unavailable, keep the time+ unknown. A relative age or Pulse's refresh time is not a matching backup+ timestamp. A **guest snapshot** is not a PBS backup. Check the existing+ backup task and verification result for that same point in PBS.3. If the records still disagree, report the Pulse version, one guest'sprotection 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.+ point's Created time, State and PBS 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.++**If PBS says verified but Pulse disagrees:** an older or absent point in Pulse+is an inventory discrepancy, before comparing verification. **Unverified** on+the matching point means Pulse has no successful verification evidence for it;+it does not prove that PBS's verification job failed. **Verified** with a+workload still needing attention is a separate assessment disagreement: retain+its explanation and Provider evidence. A **Protected** point leaves its+verification state unknown from that label alone. **Job OK** is not an+individual point's verification result. Use the records already available,+without running Diagnostics or another verification just to compare them.Do not delete backups, clear History, change retention or freshness settings,recreate tokens/connections, restart or downgrade Pulse, or run a new backup,diff --git a/frontend-modern/browser-tests/pbs-verification-help.cjs b/frontend-modern/browser-tests/pbs-verification-help.cjsnew file mode 100644index 0000000000..d5f4dfcc21--- /dev/null+++ b/frontend-modern/browser-tests/pbs-verification-help.cjs@@ -0,0 +1,130 @@+// Read-only help acceptance through the production Docs page, router and CSS.+// No PBS connection, diagnostic run or verification job is involved.+const assert = require('node:assert/strict');+const fs = require('node:fs');+const path = require('node:path');+const crypto = require('node:crypto');+const { chromium, webkit } = require('playwright');++(async () => {+ const root = '/workspace/frontend-modern';+ const artifacts = path.join(root, 'node_modules', 'pbs-verification-help-browser');+ const fragment = 'backups-are-visible-but-coverage-says-unprotected';+ const guide = fs.readFileSync(path.join(root, 'public/docs/PBS.md'));+ assert.deepEqual(guide, fs.readFileSync('/workspace/docs/PBS.md'));+ process.chdir(root);+ fs.mkdirSync(artifacts, { recursive: true });+ const { createServer } = await import(path.join(root, 'node_modules/vite/dist/node/index.js'));+ const server = await createServer({+ root, configFile: path.join(root, 'vite.config.ts'),+ cacheDir: path.join(root, 'node_modules', '.vite-pbs-verification-help'),+ server: { host: '127.0.0.1', port: 5256, strictPort: true },+ optimizeDeps: { noDiscovery: true, include: [] },+ });+ const results = [];+ let browser;+ try {+ await server.listen();+ for (const [engine, width, dark] of [['chromium', 1280, false], ['webkit', 390, true]]) {+ browser = await { chromium, webkit }[engine].launch(engine === 'chromium'+ ? { headless: true, channel: 'chromium', args: ['--no-sandbox'] }+ : { headless: true });+ const page = await browser.newPage({ viewport: { width, height: 1000 },+ ...(engine === 'webkit' ? { isMobile: true, hasTouch: true } : {}) });+ const errors = [], backendRequests = [], mutations = [], servedDocs = [];+ page.on('pageerror', (error) => errors.push(error.message));+ page.on('console', (message) => {+ if (message.type() === 'error') errors.push(message.text());+ });+ page.on('request', (request) => {+ if (!['GET', 'HEAD'].includes(request.method())) mutations.push(request.method());+ });+ page.on('response', async (response) => {+ if (new URL(response.url()).pathname === '/docs/PBS.md') {+ const bytes = await response.body();+ servedDocs.push({ status: response.status(),+ sha256: crypto.createHash('sha256').update(bytes).digest('hex') });+ }+ });+ await page.route('**/api/**', async (route) => {+ backendRequests.push(new URL(route.request().url()).pathname);+ await route.abort();+ });+ await page.goto('http://127.0.0.1:5256/browser-tests/docs-fragment-navigation.html', {+ waitUntil: 'domcontentloaded', timeout: 60000,+ });+ if (dark) await page.evaluate(() => document.documentElement.classList.add('dark'));+ await page.evaluate(() => {+ history.pushState({}, '', '/docs/RECOVERY#missing-or-inconsistent-evidence');+ dispatchEvent(new PopStateEvent('popstate'));+ });+ const entry = page.locator(`a[href="/docs/PBS#${fragment}"]`);+ await entry.waitFor({ state: 'visible' });+ assert.equal(await entry.innerText(), 'backup health checks');+ await entry.focus();+ await page.keyboard.press('Enter');+ await page.waitForFunction((id) => {+ const target = document.getElementById(id);+ const rect = target?.getBoundingClientRect();+ return target && document.activeElement === target && rect.top >= 0 && rect.top < innerHeight;+ }, fragment);+ const heading = page.locator(`#${fragment}`);+ const section = await page.evaluate((id) => {+ const target = document.getElementById(id);+ const nodes = [];+ for (let node = target.nextElementSibling; node && !/^H[1-3]$/.test(node.tagName); node = node.nextElementSibling) {+ nodes.push(node.textContent);+ }+ return nodes.join(' ').replace(/\s+/g, ' ');+ }, fragment);+ for (const phrase of [+ "Protected in a restore point's State", "not the workload's protection assessment",+ 'choose the newest point whose Source is PBS', 'Created time and State',+ 'Hover the Created age for its absolute timestamp', 'if unavailable, keep the time unknown',+ 'an older or absent point in Pulse is an inventory discrepancy',+ "does not prove that PBS's verification job failed",+ 'Verified with a workload still needing attention is a separate assessment disagreement',+ 'Protected point leaves its verification state unknown from that label alone',+ "Job OK is not an individual point's verification result",+ 'without running Diagnostics or another verification',+ 'Do not delete backups, clear History, change retention or freshness settings',+ ]) assert.ok(section.includes(phrase), `${engine}: ${phrase}`);+ assert.ok(await page.evaluate(() => document.documentElement.scrollWidth <= innerWidth + 1));+ await page.waitForFunction(() => document.getAnimations().length === 0);+ await page.screenshot({ path: path.join(artifacts, `${engine}-evidence.png`) });+ const comparison = page.locator('p').filter({ hasText: 'If PBS says verified but Pulse disagrees:' });+ await comparison.scrollIntoViewIfNeeded();+ await page.screenshot({ path: path.join(artifacts, `${engine}-comparison.png`) });+ const safety = page.getByRole('link', { name: 'Backup safety', exact: true });+ await safety.focus();+ await page.keyboard.press('Enter');+ await page.waitForFunction(() => document.activeElement?.id === 'backup-safety');+ assert.ok(await page.locator('#backup-safety').isVisible());+ assert.ok(await heading.count() === 0);+ assert.deepEqual(backendRequests, []);+ assert.deepEqual(mutations, []);+ assert.deepEqual(errors, []);+ assert.ok(servedDocs.length >= 1);+ for (const served of servedDocs) {+ assert.equal(served.status, 200);+ assert.equal(served.sha256, crypto.createHash('sha256').update(guide).digest('hex'));+ }+ results.push({ engine, browserVersion: browser.version(), width, dark,+ helpRoute: `/docs/PBS#${fragment}`, sourceMatchedResponses: servedDocs,+ recoveryEntryKeyboardNavigation: true, visibleFocusedHeading: true,+ backupSafetyKeyboardNavigation: true, noHorizontalPageOverflow: true,+ backendRequests, mutations, errors });+ await browser.close();+ browser = undefined;+ }+ } finally {+ if (browser) await browser.close();+ await server.close();+ }+ const result = { result: 'passed', playwright: require('playwright/package.json').version,+ docSha256: crypto.createHash('sha256').update(guide).digest('hex'), results,+ browserAndServerClosed: true,+ scope: 'Production documentation renderer, page, router, CSS and exact shipped Markdown; no native PBS, full application, diagnosis or release acceptance.' };+ fs.writeFileSync(path.join(artifacts, 'result.json'), JSON.stringify(result, null, 2) + '\n');+ console.log(JSON.stringify(result));+})().catch((error) => { console.error(error); process.exitCode = 1; });diff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.mdindex bfb61548c9..72f2318adf 100644--- a/frontend-modern/public/docs/PBS.md+++ b/frontend-modern/public/docs/PBS.md@@ -347,7 +347,8 @@ backup or working protection from the strip alone.| --- | --- || **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. |+| **Protected** in a restore point's **State** | That this point is verified. This displays the backup's protected flag before its verification state; it is not the workload's protection assessment. |+| **Protected**, **Attention**, **Unprotected** or **Unknown** on the workload | 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:@@ -359,14 +360,27 @@ Check one affected guest without changing its setup: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.+ installation too. Under **Restore evidence**, choose the newest point whose+ **Source** is **PBS**, and read its **Created** time and **State**. Hover the+ Created age for its absolute timestamp; if unavailable, keep the time+ unknown. A relative age or Pulse's refresh time is not a matching backup+ timestamp. A **guest snapshot** is not a PBS backup. Check the existing+ backup task and verification result for that same point in PBS.3. If the records still disagree, report the Pulse version, one guest'sprotection 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.+ point's Created time, State and PBS 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.++**If PBS says verified but Pulse disagrees:** an older or absent point in Pulse+is an inventory discrepancy, before comparing verification. **Unverified** on+the matching point means Pulse has no successful verification evidence for it;+it does not prove that PBS's verification job failed. **Verified** with a+workload still needing attention is a separate assessment disagreement: retain+its explanation and Provider evidence. A **Protected** point leaves its+verification state unknown from that label alone. **Job OK** is not an+individual point's verification result. Use the records already available,+without running Diagnostics or another verification just to compare them.Do not delete backups, clear History, change retention or freshness settings,recreate tokens/connections, restart or downgrade Pulse, or run a new backup,diff --git a/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.tsindex b51ac25a9f..c71dc97ed2 100644--- a/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts+++ b/frontend-modern/src/utils/__tests__/pbsProtectionHelp.test.ts@@ -3,6 +3,8 @@ import path from 'node:path';import { fileURLToPath } from 'node:url';import { describe, expect, it } from 'vitest';import { renderDocMarkdown } from '@/features/docs/docMarkdown';+import type { RecoverableArtifact } from '@/features/proxmox/proxmoxBackupRecoveryModel';+import { artifactStateLabel } from '@/features/proxmox/proxmoxBackupsTableShared';const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../..');const read = (file: string) => readFileSync(path.join(root, file), 'utf8');@@ -24,12 +26,14 @@ describe('PBS protection disagreement help', () => {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).toHaveLength(4);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(rows[2]).toContain("restore point's State");+ expect(rows[2]).toContain('not the workload');+ expect(rows[3]).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');});@@ -47,6 +51,11 @@ describe('PBS protection disagreement help', () => {'server, datastore, namespace (including root), guest type/ID and backup time',);expect(steps[1]).toContain('confirm the owning installation');+ expect(steps[1]).toContain('choose the newest point whose Source is PBS');+ expect(steps[1]).toContain('Created time and State');+ expect(steps[1]).toContain('Hover the Created age for its absolute timestamp');+ expect(steps[1]).toContain('if unavailable, keep the time unknown');+ expect(steps[1]).toContain('refresh time is not a matching backup timestamp');expect(steps[1]).toContain('guest snapshot is not a PBS backup');expect(steps[2]).toContain('protection explanation');expect(article().querySelector('pre')).toBeNull();@@ -56,6 +65,49 @@ describe('PBS protection disagreement help', () => {expect(coverage).toContain('Access {evidenceQualityLabel(provider.permissions)}');});+ it('distinguishes the available observations without claiming a PBS cause or verification failure', () => {+ expect(text()).toContain('an older or absent point in Pulse is an inventory discrepancy');+ expect(text()).toContain(+ 'Unverified on the matching point means Pulse has no successful verification evidence',+ );+ expect(text()).toContain("does not prove that PBS's verification job failed");+ expect(text()).toContain(+ 'Verified with a workload still needing attention is a separate assessment disagreement',+ );+ expect(text()).toContain('retain its explanation and Provider evidence');+ expect(text()).toContain("Job OK is not an individual point's verification result");+ expect(text()).toContain('without running Diagnostics or another verification');+ });++ it('keeps the Protected caution truthful for every hidden verification value', () => {+ const point: RecoverableArtifact = {+ id: 'fixture-point',+ nativeId: 'fixture-point',+ sourceKind: 'pbs',+ sourceLabel: 'PBS',+ workload: {+ key: 'fixture-guest',+ type: 'vm',+ typeLabel: 'VM',+ vmid: '100',+ label: 'Fixture VM',+ },+ createdAt: '2026-10-12T02:00:00Z',+ location: 'fixture / (root)',+ detail: '',+ protected: true,+ };+ for (const verified of [true, false, undefined]) {+ expect(artifactStateLabel({ ...point, verified })).toBe('Protected');+ }+ expect(artifactStateLabel({ ...point, protected: false, verified: true })).toBe('Verified');+ expect(artifactStateLabel({ ...point, protected: false, verified: false })).toBe('Unverified');+ expect(text()).toContain(+ 'Protected point leaves its verification state unknown from that label alone',+ );+ expect(text()).toContain("displays the backup's protected flag before its verification state");+ });+it('prevents destructive diagnostics and an assumed freshness-policy cause', () => {expect(text()).toContain('Do not delete backups, clear History, change retention or freshness settings',