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(