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
Keep guest disk permission guidance inside the intended access scope
pulse-triage[bot]eb4f3c8e3789
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.mdindex 033e3868a8..0310ad379f 100644--- a/docs/VM_DISK_MONITORING.md+++ b/docs/VM_DISK_MONITORING.md@@ -293,6 +293,13 @@ privilege separation or recreate the token to diagnose a missing reading. Seeinspection and repair boundary. A permitted read does not prove disk freshness,responsiveness or thaw.+First check whether the VM is an intended monitoring target. Keep intentionally+restricted access unchanged; do not widen the token's scope just to clear a+permission error on an excluded guest. A denied filesystem read is unavailable,+not evidence that the guest or filesystem is unhealthy. Review or change access+only for intended targets, through normal administration outside backups or+guest incidents. Table filters and alert suppression do not stop API polling.+| Collection | Proxmox VE 9+ | Proxmox VE 8 || --- | --- | --- || Filesystem usage and guest information | `VM.GuestAgent.Audit` | `VM.Monitor` |@@ -354,7 +361,7 @@ pass; do not clear or bypass a guest-read pause to test recovery.| Observation | Useful next check || --- | --- || **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |-| **Permission denied** | Review the token and account's effective read privileges on that VM, including privilege-separated token ACLs. A successful root command would not disprove this error. |+| **Permission denied** | First check whether this VM is an intended monitoring target. Preserve intentionally restricted access. For intended targets only, review the token and account's effective read privileges, including privilege-separated token ACLs, outside backups or guest incidents. A successful root command would not disprove this error; a denied read does not establish guest or filesystem health. || **Timeout or backup lock** | Check the existing backup/task timeline and guest workload locally. Defer active guest-agent probes; increasing a timeout is not a contention or thaw repair. || **Rocky Linux / RHEL memory missing** | Review `/etc/sysconfig/qemu-ga` inside the guest. File-read restrictions can explain memory collection failure; they do not by themselves prove why filesystem usage is absent. Change the guest's allowlist or restart its agent only through your normal maintenance procedure, outside backups. || **Windows service stopped** | Check the QEMU Guest Agent service inside Windows. Schedule any restart outside backups. |diff --git a/frontend-modern/browser-verification/1c48d6ea9d6a4ed3.json b/frontend-modern/browser-verification/1c48d6ea9d6a4ed3.jsonnew file mode 100644index 0000000000..0d0e471a8b--- /dev/null+++ b/frontend-modern/browser-verification/1c48d6ea9d6a4ed3.json@@ -0,0 +1,40 @@+{+ "version": 1,+ "result": "passed",+ "base_sha": "1fe65245e823a62b84f84f09997744ca1e61953b",+ "changed_paths": ["frontend-modern/src/utils/workloadGuestPresentation.ts"],+ "content_sha256": {+ "frontend-modern/src/utils/workloadGuestPresentation.ts": "ad087616ec03f0d5f18471f5eaedf5c6493fd1c008aae2362b97637dd7045cbb"+ },+ "routes": [+ "/browser-tests/guest-reading-help.html — production workload row and full GuestDrawer on synthetic readings",+ "/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis — actual shipped markdown renderer and asset"+ ],+ "states": [+ "Permission-denied filesystem reads with no current usage; retained prev-permission-denied values remain last known and lack measured utilization bars",+ "New synthetic same-guest reading removes denial guidance and restores its measured bar; unrelated missing-agent guidance unchanged",+ "Intentionally scoped access, effective account/token rights, unavailable versus unhealthy and backup precautions in shipped help"+ ],+ "interactions": [+ "Desktop keyboard Enter and phone touch open the same guest details",+ "Read wrapped error guidance and accessible row status without live diagnostics, access changes or external requests",+ "Follow existing reading-help link with keyboard or touch and view the Permissions section",+ "Inspect seven desktop/phone/narrow captures; no drawer or document horizontal overflow in checked guest states"+ ],+ "viewports": [+ {+ "width": 1365,+ "height": 900+ },+ {+ "width": 390,+ "height": 844+ },+ {+ "width": 320,+ "height": 844+ }+ ],+ "verified_at": "2026-10-09T10:50:45.951Z",+ "browser_evidence": "pulse-worker-browser tmp/guest-permission-proof/run.cjs; saved browser-command exit 0, matching final hashes/result and completed browser/server close; Playwright 1.56.1, Chromium 141.0.7390.37 and WebKit 26.0; seven final captures inspected. Outer exec session separately returned 143, initiator unknown; retained, not diagnosed or hidden. Component/help-browser acceptance only, not independent host cleanup, full-app/native collection or release acceptance."+}diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.mdindex 033e3868a8..0310ad379f 100644--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md@@ -293,6 +293,13 @@ privilege separation or recreate the token to diagnose a missing reading. Seeinspection and repair boundary. A permitted read does not prove disk freshness,responsiveness or thaw.+First check whether the VM is an intended monitoring target. Keep intentionally+restricted access unchanged; do not widen the token's scope just to clear a+permission error on an excluded guest. A denied filesystem read is unavailable,+not evidence that the guest or filesystem is unhealthy. Review or change access+only for intended targets, through normal administration outside backups or+guest incidents. Table filters and alert suppression do not stop API polling.+| Collection | Proxmox VE 9+ | Proxmox VE 8 || --- | --- | --- || Filesystem usage and guest information | `VM.GuestAgent.Audit` | `VM.Monitor` |@@ -354,7 +361,7 @@ pass; do not clear or bypass a guest-read pause to test recovery.| Observation | Useful next check || --- | --- || **Disk shows “-”** | Read its explanation and observation time. Check the owning host, current VM options, guest-local service and configured API token access. |-| **Permission denied** | Review the token and account's effective read privileges on that VM, including privilege-separated token ACLs. A successful root command would not disprove this error. |+| **Permission denied** | First check whether this VM is an intended monitoring target. Preserve intentionally restricted access. For intended targets only, review the token and account's effective read privileges, including privilege-separated token ACLs, outside backups or guest incidents. A successful root command would not disprove this error; a denied read does not establish guest or filesystem health. || **Timeout or backup lock** | Check the existing backup/task timeline and guest workload locally. Defer active guest-agent probes; increasing a timeout is not a contention or thaw repair. || **Rocky Linux / RHEL memory missing** | Review `/etc/sysconfig/qemu-ga` inside the guest. File-read restrictions can explain memory collection failure; they do not by themselves prove why filesystem usage is absent. Change the guest's allowlist or restart its agent only through your normal maintenance procedure, outside backups. || **Windows service stopped** | Check the QEMU Guest Agent service inside Windows. Schedule any restart outside backups. |diff --git a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsxindex 6289ebd98b..6700c5ca0d 100644--- a/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx+++ b/frontend-modern/src/components/Workloads/__tests__/DiskList.test.tsx@@ -86,7 +86,7 @@ describe('DiskList', () => {],['permission-denied',- 'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).',+ "Permission denied. If this VM is an intended monitoring target, review the configured account and token's effective read permissions: VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+). Do not widen intentionally scoped access just to clear this error. A denied read does not establish guest or filesystem health. Defer access changes and live probes during backups or a guest incident.",],['agent-disabled',diff --git a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsxindex c4c7e49baa..9c3156a8ea 100644--- a/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx+++ b/frontend-modern/src/components/Workloads/__tests__/GuestDrawerOverview.filesystem-provenance.test.tsx@@ -71,6 +71,40 @@ const filesystemRow = () => screen.getByText(path).closest('tr')!;afterEach(cleanup);describe('filesystem details do not promote retained usage to current health', () => {+ it.each(['permission-denied', 'prev-permission-denied'])(+ 'shows scoped-access guidance for %s and clears it only on a new reading',+ (reason) => {+ const [value, setValue] = createSignal(guest({ diskStatusReason: reason }));+ render(() => <GuestDrawerOverview {...props(value())} />);+ const message = screen.getByText(/Do not widen intentionally scoped access/);+ expect(message).toBeVisible();+ expect(message).toHaveTextContent('If this VM is an intended monitoring target');+ expect(message).toHaveTextContent('does not establish guest or filesystem health');+ expect(message).toHaveTextContent('Defer access changes and live probes during backups');+ const row = within(filesystemRow());+ expect(row.queryByRole('progressbar')).not.toBeInTheDocument();+ expect(+ row.getByText(+ reason.startsWith('prev-')+ ? 'Last known 90% · 9.00 GB/10.0 GB · EXT4'+ : 'Usage unavailable · ?/10.0 GB · EXT4',+ ),+ ).toBeVisible();+ expect(screen.getByRole('link', { name: 'Filesystem reading guidance' })).toHaveAttribute(+ 'href',+ '/docs/VM_DISK_MONITORING#a-missing-reading-is-not-an-installation-diagnosis',+ );+ setValue(guest({ diskStatusReason: '' }));+ expect(+ screen.queryByText(/Do not widen intentionally scoped access/),+ ).not.toBeInTheDocument();+ expect(within(filesystemRow()).getByRole('progressbar')).toHaveAttribute(+ 'aria-valuenow',+ '90',+ );+ },+ );+it.each(guestDiskDeferrals)('keeps prev-%s values labelled, without a current utilization bar',(reason) => {diff --git a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.tsindex 26ec9ec6dc..50c82d9bbc 100644--- a/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts+++ b/frontend-modern/src/utils/__tests__/workloadGuestPresentation.test.ts@@ -10,6 +10,25 @@ import {} from '@/utils/workloadGuestPresentation';describe('workloadGuestPresentation', () => {+ it.each(['permission-denied', 'prev-permission-denied'])(+ 'keeps %s separate from permission expansion and guest health',+ (reason) => {+ const message = getWorkloadGuestDiskStatusMessage(reason);+ expect(message).toContain('If this VM is an intended monitoring target');+ expect(message).toContain("configured account and token's effective read permissions");+ expect(message).toContain('VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+)');+ expect(message).toContain(+ 'Do not widen intentionally scoped access just to clear this error',+ );+ expect(message).toContain('A denied read does not establish guest or filesystem health');+ expect(message).toContain(+ 'Defer access changes and live probes during backups or a guest incident',+ );+ expect(message.startsWith('Using last known disk stats.')).toBe(reason.startsWith('prev-'));+ expect(message).not.toMatch(/Administrator|VM\.GuestAgent\.(Exec|FileWrite)|curl|qm agent/);+ },+ );+it.each(guestDiskDeferrals)('explains %s with and without retained disk evidence',(reason, message) => {diff --git a/frontend-modern/src/utils/workloadGuestPresentation.ts b/frontend-modern/src/utils/workloadGuestPresentation.tsindex 4e919ae6ea..00272282c5 100644--- a/frontend-modern/src/utils/workloadGuestPresentation.ts+++ b/frontend-modern/src/utils/workloadGuestPresentation.ts@@ -124,7 +124,7 @@ export function getWorkloadGuestDiskStatusMessage(reason?: string): string {case 'invalid-guest-key':return 'Guest reads unavailable because the VM identity is invalid.';case 'permission-denied':- return 'Permission denied. Check that your Pulse user/token has VM.Monitor permission (PVE 8) or VM.GuestAgent.Audit permission (PVE 9).';+ return "Permission denied. If this VM is an intended monitoring target, review the configured account and token's effective read permissions: VM.Monitor (PVE 8) or VM.GuestAgent.Audit (PVE 9+). Do not widen intentionally scoped access just to clear this error. A denied read does not establish guest or filesystem health. Defer access changes and live probes during backups or a guest incident.";case 'agent-disabled':return 'Proxmox reports the guest agent disabled in VM configuration. Review guest-OS-specific setup outside backups or guest incidents.';case 'no-filesystems':diff --git a/scripts/tests/test_pve_backup_troubleshooting_docs.py b/scripts/tests/test_pve_backup_troubleshooting_docs.pyindex c71856c7d6..1b4c5cecef 100644--- a/scripts/tests/test_pve_backup_troubleshooting_docs.py+++ b/scripts/tests/test_pve_backup_troubleshooting_docs.py@@ -81,6 +81,21 @@ class BackupAgeEvaluationDocsTest(unittest.TestCase):class PVEBackupTroubleshootingDocsTest(unittest.TestCase):+ def test_guest_disk_permission_help_preserves_intended_access_and_backup_safety(self):+ guide = (ROOT / "docs/VM_DISK_MONITORING.md").read_text()+ section = guide.split("## ⚙️ Permissions\n", 1)[1].split("\n## ", 1)[0]+ text = " ".join(section.split())+ for distinction in ("VM is an intended monitoring target",+ "Keep intentionally restricted access unchanged",+ "do not widen the token's scope",+ "not evidence that the guest or filesystem is unhealthy",+ "only for intended targets", "outside backups or guest incidents",+ "Table filters and alert suppression do not stop API polling"):+ self.assertIn(distinction, text)+ self.assertNotIn("```", section, "no copied grant or live guest probe")+ self.assertEqual((ROOT / "docs/VM_DISK_MONITORING.md").read_bytes(),+ (ROOT / "frontend-modern/public/docs/VM_DISK_MONITORING.md").read_bytes())+def test_intentionally_restricted_cluster_is_not_an_access_repair_recipe(self):trouble = (ROOT / "docs/TROUBLESHOOTING.md").read_text()section = trouble.split("### Check Permissions (Proxmox)\n", 1)[1].split("\n### ", 1)[0]