From c851f46ef8ef97c69e13a8b044d36ace63bc2000 Mon Sep 17 00:00:00 2001 From: "pulse-triage[bot]" <249995291+pulse-triage[bot]@users.noreply.github.com> Date: Tue, 6 Oct 2026 02:49:30 +0100 Subject: [PATCH] Keep VM disk FAQ out of unsafe installation assumptions A disk dash does not diagnose an absent or stopped agent. Keep setup specific to the supported guest OS, defer live changes during backup or guest incidents, and require independent recovery rather than treating a retained reading or an OK backup as current evidence. Link the existing guidance and cover its rendered destinations and shipped mirror. Contract-Neutral: Documentation and rendered-help coverage only; no runtime, data, API or permission contract changes. Change-source: pulse-maintainer --- docs/FAQ.md | 20 ++++++++++-- frontend-modern/public/docs/FAQ.md | 20 ++++++++++-- .../utils/__tests__/backupSafetyHelp.test.ts | 32 +++++++++++++++++++ 3 files changed, 68 insertions(+), 4 deletions(-) diff --git a/docs/FAQ.md b/docs/FAQ.md index e5d221ca21..a13e528bf6 100644 --- a/docs/FAQ.md +++ b/docs/FAQ.md @@ -63,8 +63,24 @@ Pushover destination under **Alerts** and open Pulse in your phone's browser. See [Relay / Pulse Mobile](RELAY.md) for the existing pairing and security details. ### Why do VMs show "-" for disk usage? -Proxmox API returns `0` for VM disk usage by default. You must install the **QEMU Guest Agent** inside the VM and enable it in Proxmox (VM → Options → QEMU Guest Agent). -See [VM Disk Monitoring](VM_DISK_MONITORING.md) for details. + +A dash means filesystem usage is unavailable, **not zero**. Allocated virtual-disk +size is not used space inside the guest. Pulse can read that usage through a +supported QEMU Guest Agent, but a failed read does not establish that the agent +is absent or stopped. Read the explanation and observation time; use the guest's +own filesystem readings rather than treating a retained Pulse value as current. + +Do not install, enable or restart an agent solely to clear a disk dash. During a +backup, freeze/thaw or an unresponsive-guest incident, defer setup and live probes. +Follow [Backup safety](VM_DISK_MONITORING.md#backup-safety); an OK backup does not +prove thaw. Keep the monitoring-outage precaution until independent checks confirm +thaw, fresh writes to every covered filesystem and workload liveness. Restore only +services and timers that were previously active. + +Outside those conditions, review the existing configuration and supported setup +for the guest OS. The Linux package name is not a Windows or Android installation +instruction; if no supported agent is available, use guest-local filesystem tools. +See [Missing-reading and setup guidance](VM_DISK_MONITORING.md#a-missing-reading-is-not-an-installation-diagnosis). ### Does Pulse monitor Ceph? Yes! If Pulse detects Ceph storage, it automatically queries cluster health, OSD status, and pool usage. No extra config needed. diff --git a/frontend-modern/public/docs/FAQ.md b/frontend-modern/public/docs/FAQ.md index e5d221ca21..a13e528bf6 100644 --- a/frontend-modern/public/docs/FAQ.md +++ b/frontend-modern/public/docs/FAQ.md @@ -63,8 +63,24 @@ Pushover destination under **Alerts** and open Pulse in your phone's browser. See [Relay / Pulse Mobile](RELAY.md) for the existing pairing and security details. ### Why do VMs show "-" for disk usage? -Proxmox API returns `0` for VM disk usage by default. You must install the **QEMU Guest Agent** inside the VM and enable it in Proxmox (VM → Options → QEMU Guest Agent). -See [VM Disk Monitoring](VM_DISK_MONITORING.md) for details. + +A dash means filesystem usage is unavailable, **not zero**. Allocated virtual-disk +size is not used space inside the guest. Pulse can read that usage through a +supported QEMU Guest Agent, but a failed read does not establish that the agent +is absent or stopped. Read the explanation and observation time; use the guest's +own filesystem readings rather than treating a retained Pulse value as current. + +Do not install, enable or restart an agent solely to clear a disk dash. During a +backup, freeze/thaw or an unresponsive-guest incident, defer setup and live probes. +Follow [Backup safety](VM_DISK_MONITORING.md#backup-safety); an OK backup does not +prove thaw. Keep the monitoring-outage precaution until independent checks confirm +thaw, fresh writes to every covered filesystem and workload liveness. Restore only +services and timers that were previously active. + +Outside those conditions, review the existing configuration and supported setup +for the guest OS. The Linux package name is not a Windows or Android installation +instruction; if no supported agent is available, use guest-local filesystem tools. +See [Missing-reading and setup guidance](VM_DISK_MONITORING.md#a-missing-reading-is-not-an-installation-diagnosis). ### Does Pulse monitor Ceph? Yes! If Pulse detects Ceph storage, it automatically queries cluster health, OSD status, and pool usage. No extra config needed. diff --git a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts index 4f31933bb1..09db0b2fbd 100644 --- a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts +++ b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts @@ -19,6 +19,38 @@ function render(markdown: string, name: string): HTMLElement { } describe('manual backup safety help', () => { + it('does not turn a FAQ disk dash into mandatory installation or unsafe recovery', () => { + const faq = read('docs/FAQ.md'); + expect(read('frontend-modern/public/docs/FAQ.md')).toBe(faq); + const section = faq.split('### Why do VMs show "-" for disk usage?')[1]?.split('\n### ')[0]; + expect(section).toBeTruthy(); + const rendered = render(section!, 'FAQ'); + const text = rendered.textContent?.replace(/\s+/g, ' '); + expect(text).toContain('unavailable, not zero'); + expect(text).toContain('does not establish that the agent is absent or stopped'); + expect(text).toContain('rather than treating a retained Pulse value as current'); + expect(text).toContain( + 'Do not install, enable or restart an agent solely to clear a disk dash', + ); + expect(text).toContain('defer setup and live probes'); + expect(text).toContain('an OK backup does not prove thaw'); + expect(text).toContain('monitoring-outage precaution'); + expect(text).toContain('fresh writes to every covered filesystem and workload liveness'); + expect(text).toContain('Restore only services and timers that were previously active'); + expect(text).toContain('not a Windows or Android installation instruction'); + expect(text).not.toMatch(/You must install|Enable it in VM Options|qm agent/); + expect(rendered.querySelector('pre')).toBeNull(); + const target = render(guide, 'VM_DISK_MONITORING'); + for (const [label, fragment] of [ + ['Backup safety', 'backup-safety'], + ['Missing-reading and setup guidance', 'a-missing-reading-is-not-an-installation-diagnosis'], + ]) { + const link = rendered.querySelector(`a[href="/docs/VM_DISK_MONITORING#${fragment}"]`); + expect(link?.textContent).toBe(label); + expect(target.querySelector(`#${fragment}`)).not.toBeNull(); + } + }); + it('makes missing-reading guidance observational, OS-specific and safe before setup', () => { const rendered = render(guide, 'VM_DISK_MONITORING'); const troubleshooting = rendered.querySelector(