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 missing backup placement without confusing repository identity
pulse-triage[bot]0ec511193e8c
diff --git a/docs/PBS.md b/docs/PBS.mdindex 5a7f9b3951..91b177875d 100644--- a/docs/PBS.md+++ b/docs/PBS.md@@ -597,6 +597,9 @@ from a PBS-backed storage target. If that explanation is unavailable, keep theorigin unknown rather than inferring it from a matching guest ID or name.A source label is not a protection, verification, restore or thaw result.+Keep the backup repository separate from+[guest placement and Node filters](RECOVERY.md#backup-location-and-guest-placement),+especially when a PBS backup has no reported PVE owner or node.**PVE/PBS inventory loading or unavailable** notices mean counts are incomplete,not that missing backups do not exist. Existing PBS and PVE observations canrefer to the same backup; compare their owning installation, storage,diff --git a/docs/RECOVERY.md b/docs/RECOVERY.mdindex 98ca99467a..a788b57934 100644--- a/docs/RECOVERY.md+++ b/docs/RECOVERY.md@@ -161,6 +161,42 @@ VMIDs alone are not sufficient to identify a duplicate or the right restore.Direct PBS observations and PBS-through-PVE observations can differ in detail.See [PBS data sources](PBS.md#data-source-indicator).+### Backup location and guest placement++In **Coverage** and **By date**, expand the workload or backup row before+deciding which installation owns it. Keep these identities separate:++| Evidence | Meaning and limit |+|---|---|+| Workload type, **Target ID**, **PVE connection** and **Node** | The guest and its reported PVE scope and placement. A VMID is unique only within its owning installation; a missing connection or node stays **Not reported**. |+| Artifact **Source** and **Location** | The inventory reader and backup repository, including a PBS datastore or namespace. A repository name is not a guest node, and its reader is not necessarily the guest's owning PVE connection. |+| **Provider evidence → Scope** | The collection context for that evidence, not a substitute for missing workload ownership or placement. |++**Node: Not reported** does not mean that a backup failed, a guest was deleted+or its node is offline. An unmatched PBS backup may retain its repository and+guest type/ID without a known PVE owner. Do not infer that owner or node from+the datastore, namespace, connection label or a repeated VMID. Older versions+may have shown one of those hints as a Node; that label alone is not native+placement evidence.++The **Node** filter offers reported placement, not every backup location.+If an expected row is absent under a selected node, choose **All nodes** and+compare its **Backup location** or search for its repository instead. A+namespace missing from the Node options is not evidence that its backups are+missing. Clearing a display filter neither refreshes collection nor repairs+identity or protection posture. On a phone, expand the row to read its full+source and location rather than relying on the shortened summary.++Compare existing provider records with consistent private aliases for the+installation, guest type/ID, repository and time. Keep unknown ownership+unknown; do not rename nodes, move backups, widen permissions or recreate a+connection to fill the label. Keep full identifiers and private paths out of+public reports. If node errors or agent-backed Docker readings are also mixed,+follow the [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations):+one corrected backup label does not establish recovery in those other views.+An unresponsive guest or uncertain thaw needs the separate+[backup safety procedure](VM_DISK_MONITORING.md#backup-safety), not a filter change.+### Outcomes and verificationRecorded outcomes are `success`, `warning`, `failed`, `running` or `unknown`.diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 93cd586bed..da08657d7a 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -828,7 +828,7 @@ than undoing the repair or repeating the addition.| Affected reading | Safe comparison | What it does not prove || --- | --- | --- || Node errors | Compare the affected node and observation time with that installation's own Proxmox view. | A similar node name or a different Pulse label does not establish which installation owns the error. |-| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected). | The same VMID or a visible backup from another installation does not establish protection for this guest. |+| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected) and distinguish [backup location from guest placement](RECOVERY.md#backup-location-and-guest-placement). | The same VMID or a visible backup from another installation does not establish protection for this guest. || Agent-backed Docker monitoring | In **Settings → Infrastructure → Agent Doctor**, inspect the affected host's existing **Last seen** and **Identity evidence**, including **Connection** and **Hostname** where available. Compare with the known Docker host, not a similar guest name. | Recent agent contact or a Healthy badge does not prove that the correct host's containers are visible or correctly attributed. Missing evidence is unknown, not proof that the agent stopped. |While attribution is uncertain, use each installation's own Proxmox/PBSdiff --git a/frontend-modern/public/docs/PBS.md b/frontend-modern/public/docs/PBS.mdindex 5a7f9b3951..91b177875d 100644--- a/frontend-modern/public/docs/PBS.md+++ b/frontend-modern/public/docs/PBS.md@@ -597,6 +597,9 @@ from a PBS-backed storage target. If that explanation is unavailable, keep theorigin unknown rather than inferring it from a matching guest ID or name.A source label is not a protection, verification, restore or thaw result.+Keep the backup repository separate from+[guest placement and Node filters](RECOVERY.md#backup-location-and-guest-placement),+especially when a PBS backup has no reported PVE owner or node.**PVE/PBS inventory loading or unavailable** notices mean counts are incomplete,not that missing backups do not exist. Existing PBS and PVE observations canrefer to the same backup; compare their owning installation, storage,diff --git a/frontend-modern/public/docs/RECOVERY.md b/frontend-modern/public/docs/RECOVERY.mdindex 98ca99467a..a788b57934 100644--- a/frontend-modern/public/docs/RECOVERY.md+++ b/frontend-modern/public/docs/RECOVERY.md@@ -161,6 +161,42 @@ VMIDs alone are not sufficient to identify a duplicate or the right restore.Direct PBS observations and PBS-through-PVE observations can differ in detail.See [PBS data sources](PBS.md#data-source-indicator).+### Backup location and guest placement++In **Coverage** and **By date**, expand the workload or backup row before+deciding which installation owns it. Keep these identities separate:++| Evidence | Meaning and limit |+|---|---|+| Workload type, **Target ID**, **PVE connection** and **Node** | The guest and its reported PVE scope and placement. A VMID is unique only within its owning installation; a missing connection or node stays **Not reported**. |+| Artifact **Source** and **Location** | The inventory reader and backup repository, including a PBS datastore or namespace. A repository name is not a guest node, and its reader is not necessarily the guest's owning PVE connection. |+| **Provider evidence → Scope** | The collection context for that evidence, not a substitute for missing workload ownership or placement. |++**Node: Not reported** does not mean that a backup failed, a guest was deleted+or its node is offline. An unmatched PBS backup may retain its repository and+guest type/ID without a known PVE owner. Do not infer that owner or node from+the datastore, namespace, connection label or a repeated VMID. Older versions+may have shown one of those hints as a Node; that label alone is not native+placement evidence.++The **Node** filter offers reported placement, not every backup location.+If an expected row is absent under a selected node, choose **All nodes** and+compare its **Backup location** or search for its repository instead. A+namespace missing from the Node options is not evidence that its backups are+missing. Clearing a display filter neither refreshes collection nor repairs+identity or protection posture. On a phone, expand the row to read its full+source and location rather than relying on the shortened summary.++Compare existing provider records with consistent private aliases for the+installation, guest type/ID, repository and time. Keep unknown ownership+unknown; do not rename nodes, move backups, widen permissions or recreate a+connection to fill the label. Keep full identifiers and private paths out of+public reports. If node errors or agent-backed Docker readings are also mixed,+follow the [cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations):+one corrected backup label does not establish recovery in those other views.+An unresponsive guest or uncertain thaw needs the separate+[backup safety procedure](VM_DISK_MONITORING.md#backup-safety), not a filter change.+### Outcomes and verificationRecorded outcomes are `success`, `warning`, `failed`, `running` or `unknown`.diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex 93cd586bed..da08657d7a 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -828,7 +828,7 @@ than undoing the repair or repeating the addition.| Affected reading | Safe comparison | What it does not prove || --- | --- | --- || Node errors | Compare the affected node and observation time with that installation's own Proxmox view. | A similar node name or a different Pulse label does not establish which installation owns the error. |-| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected). | The same VMID or a visible backup from another installation does not establish protection for this guest. |+| Guest backup status | Compare one affected guest with the matching native Proxmox/PBS record: owning installation, guest type/VMID, datastore, namespace and backup time. Follow the [PBS evidence checks](PBS.md#backups-are-visible-but-coverage-says-unprotected) and distinguish [backup location from guest placement](RECOVERY.md#backup-location-and-guest-placement). | The same VMID or a visible backup from another installation does not establish protection for this guest. || Agent-backed Docker monitoring | In **Settings → Infrastructure → Agent Doctor**, inspect the affected host's existing **Last seen** and **Identity evidence**, including **Connection** and **Hostname** where available. Compare with the known Docker host, not a similar guest name. | Recent agent contact or a Healthy badge does not prove that the correct host's containers are visible or correctly attributed. Missing evidence is unknown, not proof that the agent stopped. |While attribution is uncertain, use each installation's own Proxmox/PBSdiff --git a/frontend-modern/src/features/docs/__tests__/backupPlacementGuide.test.ts b/frontend-modern/src/features/docs/__tests__/backupPlacementGuide.test.tsnew file mode 100644index 0000000000..78d0c8af11--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/backupPlacementGuide.test.ts@@ -0,0 +1,106 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import {+ getBackupWorkloadNodeLabel,+ getBackupWorkloadPVEConnection,+} from '@/features/proxmox/proxmoxBackupsTableShared';+import { type WorkloadReference } from '@/features/proxmox/proxmoxBackupRecoveryModel';+import { createGuideFixture } from './guideFixture';++const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');+const read = (file: string) => readFileSync(path.join(root, file), 'utf8');+const guide = createGuideFixture((name) =>+ readFileSync(+ path.join(+ process.env.PULSE_BACKUP_PLACEMENT_GUIDE_INPUT_DIRECTORY ??+ path.join(root, 'frontend-modern/public/docs'),+ `${name}.md`,+ ),+ 'utf8',+ ),+);+const fragment = '#backup-location-and-guest-placement';+const section = () => {+ const heading = guide('RECOVERY').querySelector(fragment);+ expect(heading?.textContent).toBe('Backup location and guest placement');+ const result = document.createElement('section');+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {+ if (/^H[1-3]$/.test(next.tagName)) break;+ result.appendChild(next.cloneNode(true));+ }+ return result;+};+const prose = () => section().textContent!.replace(/\s+/g, ' ');++describe('backup placement guidance', () => {+ it('keeps discovery links and shipped copies aligned', () => {+ for (const name of ['PBS', 'TROUBLESHOOTING']) {+ expect(guide(name).querySelector(`a[href="/docs/RECOVERY${fragment}"]`)).not.toBeNull();+ }+ for (const name of ['RECOVERY', 'PBS', 'TROUBLESHOOTING']) {+ expect(read(`docs/${name}.md`)).toBe(read(`frontend-modern/public/docs/${name}.md`));+ }+ });++ it('distinguishes reported guest placement from repository and reader scope', () => {+ const rows = [...section().querySelectorAll('tbody tr')];+ expect(rows).toHaveLength(3);+ expect(rows[0].textContent).toContain('Target ID');+ expect(rows[0].textContent).toContain('PVE connection');+ expect(rows[1].textContent).toContain('A repository name is not a guest node');+ expect(rows[2].textContent).toContain('not a substitute for missing workload ownership');+ const unmatched: WorkloadReference = {+ key: 'pbs:private-example:vm/100',+ type: 'vm',+ typeLabel: 'VM',+ vmid: '100',+ label: 'VM 100',+ };+ expect(rows[0].textContent).toContain(getBackupWorkloadNodeLabel(unmatched));+ expect(rows[0].textContent).toContain(getBackupWorkloadPVEConnection(unmatched));+ for (const distinction of [+ 'does not mean that a backup failed, a guest was deleted or its node is offline',+ 'without a known PVE owner',+ 'Do not infer that owner or node from the datastore, namespace, connection label or a repeated VMID',+ 'that label alone is not native placement evidence',+ ]) {+ expect(prose()).toContain(distinction);+ }+ });++ it('finds unmatched evidence without treating a display filter as repair', () => {+ for (const distinction of [+ 'Node filter offers reported placement, not every backup location',+ 'choose All nodes',+ 'Backup location or search for its repository',+ 'not evidence that its backups are missing',+ 'neither refreshes collection nor repairs identity or protection posture',+ 'On a phone, expand the row',+ ]) {+ expect(prose()).toContain(distinction);+ }+ });++ it('keeps comparison private and partial recovery distinct from original symptoms', () => {+ for (const boundary of [+ 'Compare existing provider records',+ 'Keep unknown ownership unknown',+ 'do not rename nodes, move backups, widen permissions or recreate a connection',+ 'Keep full identifiers and private paths out of public reports',+ 'one corrected backup label does not establish recovery in those other views',+ 'An unresponsive guest or uncertain thaw needs the separate backup safety procedure',+ ]) {+ expect(prose()).toContain(boundary);+ }+ expect(section().querySelector('pre')).toBeNull();+ for (const [name, target] of [+ ['TROUBLESHOOTING', '#monitoring-is-mixed-between-proxmox-installations'],+ ['VM_DISK_MONITORING', '#backup-safety'],+ ]) {+ expect(section().querySelector(`a[href="/docs/${name}${target}"]`)).not.toBeNull();+ expect(guide(name).querySelector(target)).not.toBeNull();+ }+ });+});