Skip to content

armgit / Pulse

Public Imported from GitHub
0

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.

Keep VM disk FAQ out of unsafe installation assumptions

pulse-triage[bot]c851f46ef8ef
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(