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.

Offer existing Machines disk readings without changing affected guests

pulse-triage[bot]7da8c65397a9
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.md
index aeddc4cabc..582e87d267 100644
--- a/docs/VM_DISK_MONITORING.md
+++ b/docs/VM_DISK_MONITORING.md
@@ -321,6 +321,30 @@ supported QEMU Guest Agent. The Linux package name is not a Windows or Android
installation instruction. If no supported agent is available, use the guest's
own filesystem tools; missing Pulse usage is unknown, not zero.
+### Use existing Machines readings without changing the guest
+
+The Proxmox disk view and an in-guest **Pulse Agent** use different collection
+paths. A paused Proxmox guest-agent read does not mean the Pulse Agent has
+stopped reporting. If the affected VM **already has a Pulse Agent** and an
+existing entry in **Machines**, check that view's filesystem readings and
+History before changing anything in the guest.
+
+Confirm the Machines entry belongs to the **same guest**, using its existing
+identity and host details, not a similar name alone. Check the filesystem and
+its observation time: a retained History sample or an agent's recent contact
+is not proof of a current disk reading. Use available, current readings there
+as an interim view; this does not repair the missing Proxmox reading or prove
+that the two entries are linked correctly. If the guest has no existing Pulse
+Agent entry or no current filesystem readings, use its own filesystem tools
+through your normal interface. **Do not install another agent, restart services,
+restore a VM or force guest-agent checks just to recover these readings.**
+
+This alternative does **not** relax [Backup safety](#backup-safety). A responsive
+guest, running agent services, working Machines readings or an expired cooldown
+is not proof of thaw and successful writes to every filesystem covered by the
+backup. Keep the monitoring-outage precaution until those independent checks
+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. |
diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
index fc0406dcf0..e0c98462e1 100644
--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md
+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md
@@ -8787,3 +8787,15 @@ title as a muted line (`data-thresholds-defaults-summary`) that wraps only
between items on phones and truncates from `sm` up, and is hidden while
`isGloballyDisabled` is set, where it would promise alerts that cannot fire. Callers pass the shared summary helper's output rather than
composing per-section strings.
+
+### Passive alternative for unavailable Proxmox guest disks (6 October 2026)
+
+The existing disk guide offers already-present Machines filesystem readings and
+History as an interim view, with same-guest identity and metric-age checks.
+Recent agent contact and retained History do not establish current disk usage;
+working Machines readings do not repair Proxmox collection or prove correlation
+or thaw. No new agent installation, guest restart/restore, pause bypass or active
+probe is prescribed. Independent thaw, every-covered-filesystem writes and
+liveness remain the backup restoration boundary. The shipped mirror and
+`backupSafetyHelp.test.ts` validate the rendered guidance and anchor; both new
+controls reject the original parent guide. No runtime or wire contract changes.
diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.md
index aeddc4cabc..582e87d267 100644
--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md
+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md
@@ -321,6 +321,30 @@ supported QEMU Guest Agent. The Linux package name is not a Windows or Android
installation instruction. If no supported agent is available, use the guest's
own filesystem tools; missing Pulse usage is unknown, not zero.
+### Use existing Machines readings without changing the guest
+
+The Proxmox disk view and an in-guest **Pulse Agent** use different collection
+paths. A paused Proxmox guest-agent read does not mean the Pulse Agent has
+stopped reporting. If the affected VM **already has a Pulse Agent** and an
+existing entry in **Machines**, check that view's filesystem readings and
+History before changing anything in the guest.
+
+Confirm the Machines entry belongs to the **same guest**, using its existing
+identity and host details, not a similar name alone. Check the filesystem and
+its observation time: a retained History sample or an agent's recent contact
+is not proof of a current disk reading. Use available, current readings there
+as an interim view; this does not repair the missing Proxmox reading or prove
+that the two entries are linked correctly. If the guest has no existing Pulse
+Agent entry or no current filesystem readings, use its own filesystem tools
+through your normal interface. **Do not install another agent, restart services,
+restore a VM or force guest-agent checks just to recover these readings.**
+
+This alternative does **not** relax [Backup safety](#backup-safety). A responsive
+guest, running agent services, working Machines readings or an expired cooldown
+is not proof of thaw and successful writes to every filesystem covered by the
+backup. Keep the monitoring-outage precaution until those independent checks
+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. |
diff --git a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts
index 2c5482a816..e3962d3193 100644
--- a/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts
+++ b/frontend-modern/src/utils/__tests__/backupSafetyHelp.test.ts
@@ -207,7 +207,9 @@ describe('manual backup safety help', () => {
const text = render(section, 'VM_DISK_MONITORING').textContent?.replace(/\s+/g, ' ');
expect(text).toContain('Stopping Pulse does not cancel a guest-agent request already issued');
expect(text).toContain('Even a successful process exit does not prove');
- expect(text).toContain('Let existing guest/backup operations finish normally before the planned backup');
+ expect(text).toContain(
+ 'Let existing guest/backup operations finish normally before the planned backup',
+ );
expect(text).toContain('not new guest-agent probes');
expect(text).toContain('If their state is unknown, do not start the backup');
expect(text).toContain('a stopped service or an arbitrary waiting period');
@@ -240,4 +242,50 @@ describe('manual backup safety help', () => {
/qm |pct |pvesh |guest-fsfreeze|restart|disable|enable|mask|reset|rm |kill|curl|wget|Environment/,
);
});
+ it('offers existing Machines disk readings without assuming identity, freshness or a repaired link', () => {
+ expect(read('frontend-modern/public/docs/VM_DISK_MONITORING.md')).toBe(guide);
+ const alternative = guide
+ .split('### Use existing Machines readings without changing the guest')[1]
+ ?.split('| Observation |')[0];
+ expect(alternative).toBeTruthy();
+ const rendered = render(alternative!, 'VM_DISK_MONITORING');
+ const text = rendered.textContent?.replace(/\s+/g, ' ');
+ expect(text).toContain('use different collection paths');
+ expect(text).toContain('already has a Pulse Agent');
+ expect(text).toContain('existing entry in Machines');
+ expect(text).toContain('same guest');
+ expect(text).toContain('not a similar name alone');
+ expect(text).toContain(
+ "a retained History sample or an agent's recent contact is not proof of a current disk reading",
+ );
+ expect(text).toContain('does not repair the missing Proxmox reading');
+ expect(text).toContain('prove that the two entries are linked correctly');
+ expect(text).toContain('no current filesystem readings, use its own filesystem tools');
+ expect(rendered.querySelector('pre')).toBeNull();
+ });
+
+ it('keeps the Machines workaround separate from guest changes and independent backup recovery', () => {
+ const alternative = guide
+ .split('### Use existing Machines readings without changing the guest')[1]
+ ?.split('| Observation |')[0];
+ expect(alternative).toBeTruthy();
+ const rendered = render(alternative!, 'VM_DISK_MONITORING');
+ const text = rendered.textContent?.replace(/\s+/g, ' ');
+ expect(text).toContain(
+ 'Do not install another agent, restart services, restore a VM or force guest-agent checks',
+ );
+ expect(text).toContain('does not relax Backup safety');
+ expect(text).toContain(
+ 'A responsive guest, running agent services, working Machines readings or an expired cooldown is not proof of thaw',
+ );
+ expect(text).toContain('successful writes to every filesystem covered by the backup');
+ expect(text).toContain('Keep the monitoring-outage precaution');
+ expect(text).toContain('do not clear or bypass a guest-read pause');
+ const target = render(guide, 'VM_DISK_MONITORING');
+ expect(
+ target.querySelector('#use-existing-machines-readings-without-changing-the-guest'),
+ ).not.toBeNull();
+ expect(rendered.querySelector('a[href="#backup-safety"]')).not.toBeNull();
+ expect(target.querySelector('#backup-safety')).not.toBeNull();
+ });
});