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 Windows guest-read diagnosis separate from Linux file permissions

pulse-triage[bot]ff862da592f8
diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.md
index 0286b4b4b5..506758fb18 100644
--- a/docs/VM_DISK_MONITORING.md
+++ b/docs/VM_DISK_MONITORING.md
@@ -303,7 +303,13 @@ 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` |
-| Reading guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+| Reading Linux guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+
+Windows has no `/proc/meminfo`. A failure reading that Linux path is not evidence
+that Windows filesystem collection needs `VM.GuestAgent.FileRead` or that the
+guest agent is stopped. Keep memory-file access separate from filesystem access;
+see [Windows readings after a Pulse restart](#windows-readings-after-a-pulse-restart)
+before changing permissions or services.
Do not grant Administrator or guest execution/write permissions to diagnose a
missing disk value. The built-in `PVEAuditor` role cannot be modified; use a
@@ -377,6 +383,31 @@ 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.
+### Windows readings after a Pulse restart
+
+If Windows disks become **Unavailable** after Pulse restarts, a
+**guest reads paused** or `agent-cooldown` explanation describes Pulse's deferred
+collection, not a stopped Windows service or proof that the guest is frozen.
+Windows does not provide the Linux `/proc/meminfo` file. An existing HTTP 500
+for that file alone does not establish why filesystem reads are missing; do not
+grant more privileges or change the guest's file-read policy to make it succeed.
+
+Keep the original sequence: which readings worked before the Pulse restart,
+the existing error and times, and whether normal Windows use remained responsive.
+A later working reading from a Pulse Agent is a different collection path, not
+confirmation that QEMU Guest Agent reads recovered. For capacity decisions, use
+Windows' own filesystem view or
+[current readings from an already installed Pulse Agent](#use-existing-machines-readings-without-changing-the-guest).
+Keep the same guest identity, filesystem and observation time with the comparison.
+
+Do not repeat the restart, run Diagnostics or guest-agent probes, clear a
+cooldown, or install, remove or restart either agent just to diagnose this state.
+If those observations are already in your report, do not collect them again.
+An expired cooldown or a number returning is not proof that every volume or
+History recovered. If the workload is unresponsive or a backup is involved,
+[Backup safety](#backup-safety) takes precedence; these interim views do not
+prove thaw or successful writes.
+
### Use existing Machines readings without changing the guest
The Proxmox disk view and an in-guest **Pulse Agent** use different collection
diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.md
index 0286b4b4b5..506758fb18 100644
--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md
+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md
@@ -303,7 +303,13 @@ 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` |
-| Reading guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+| Reading Linux guest memory via `/proc/meminfo` | Also `VM.GuestAgent.FileRead` | `VM.Monitor` |
+
+Windows has no `/proc/meminfo`. A failure reading that Linux path is not evidence
+that Windows filesystem collection needs `VM.GuestAgent.FileRead` or that the
+guest agent is stopped. Keep memory-file access separate from filesystem access;
+see [Windows readings after a Pulse restart](#windows-readings-after-a-pulse-restart)
+before changing permissions or services.
Do not grant Administrator or guest execution/write permissions to diagnose a
missing disk value. The built-in `PVEAuditor` role cannot be modified; use a
@@ -377,6 +383,31 @@ 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.
+### Windows readings after a Pulse restart
+
+If Windows disks become **Unavailable** after Pulse restarts, a
+**guest reads paused** or `agent-cooldown` explanation describes Pulse's deferred
+collection, not a stopped Windows service or proof that the guest is frozen.
+Windows does not provide the Linux `/proc/meminfo` file. An existing HTTP 500
+for that file alone does not establish why filesystem reads are missing; do not
+grant more privileges or change the guest's file-read policy to make it succeed.
+
+Keep the original sequence: which readings worked before the Pulse restart,
+the existing error and times, and whether normal Windows use remained responsive.
+A later working reading from a Pulse Agent is a different collection path, not
+confirmation that QEMU Guest Agent reads recovered. For capacity decisions, use
+Windows' own filesystem view or
+[current readings from an already installed Pulse Agent](#use-existing-machines-readings-without-changing-the-guest).
+Keep the same guest identity, filesystem and observation time with the comparison.
+
+Do not repeat the restart, run Diagnostics or guest-agent probes, clear a
+cooldown, or install, remove or restart either agent just to diagnose this state.
+If those observations are already in your report, do not collect them again.
+An expired cooldown or a number returning is not proof that every volume or
+History recovered. If the workload is unresponsive or a backup is involved,
+[Backup safety](#backup-safety) takes precedence; these interim views do not
+prove thaw or successful writes.
+
### Use existing Machines readings without changing the guest
The Proxmox disk view and an in-guest **Pulse Agent** use different collection
diff --git a/frontend-modern/src/features/docs/__tests__/proxmoxPermissionsGuide.test.ts b/frontend-modern/src/features/docs/__tests__/proxmoxPermissionsGuide.test.ts
index da97a6db80..73ad242349 100644
--- a/frontend-modern/src/features/docs/__tests__/proxmoxPermissionsGuide.test.ts
+++ b/frontend-modern/src/features/docs/__tests__/proxmoxPermissionsGuide.test.ts
@@ -121,4 +121,49 @@ describe('shipped Proxmox permission diagnosis', () => {
);
}
});
+
+ it('keeps Linux memory-file privileges separate from Windows filesystem access', () => {
+ const article = renderGuide('VM_DISK_MONITORING');
+ const row = [...article.querySelectorAll('tr')].find((element) =>
+ prose(element as HTMLElement).startsWith('Reading Linux guest memory'),
+ );
+ expect(prose(row as HTMLElement)).toContain('/proc/meminfo');
+ expect(prose(row as HTMLElement)).toContain('VM.GuestAgent.FileRead');
+ expect(prose(article)).toContain('Windows has no /proc/meminfo');
+ expect(prose(article)).toContain(
+ 'not evidence that Windows filesystem collection needs VM.GuestAgent.FileRead',
+ );
+ expect(
+ article.querySelector('a[href="/docs/VM_DISK_MONITORING#windows-readings-after-a-pulse-restart"]'),
+ ).not.toBeNull();
+ expect(article.querySelector('#windows-readings-after-a-pulse-restart')).not.toBeNull();
+ });
+
+ it('explains the Windows restart state without diagnosing agent failure or recovery', () => {
+ const content = section(renderGuide('VM_DISK_MONITORING'), 'windows-readings-after-a-pulse-restart');
+ const text = prose(content);
+ expect(text).toContain('agent-cooldown');
+ expect(text).toContain("describes Pulse's deferred collection");
+ expect(text).toContain('not a stopped Windows service or proof that the guest is frozen');
+ expect(text).toContain('An existing HTTP 500 for that file alone does not establish why');
+ expect(text).toContain('not confirmation that QEMU Guest Agent reads recovered');
+ expect(text).toContain('not proof that every volume or History recovered');
+ expect(content.querySelector('pre')).toBeNull();
+ });
+
+ it('offers existing Windows or agent readings without new probes, privilege or state churn', () => {
+ const content = section(renderGuide('VM_DISK_MONITORING'), 'windows-readings-after-a-pulse-restart');
+ const text = prose(content);
+ expect(text).toContain("Windows' own filesystem view");
+ expect(text).toContain('same guest identity, filesystem and observation time');
+ expect(text).toContain('do not grant more privileges');
+ expect(text).toContain('Do not repeat the restart, run Diagnostics or guest-agent probes');
+ expect(text).toContain('clear a cooldown, or install, remove or restart either agent');
+ expect(text).toContain('do not collect them again');
+ expect(text).toContain('these interim views do not prove thaw or successful writes');
+ for (const fragment of ['use-existing-machines-readings-without-changing-the-guest', 'backup-safety']) {
+ expect(content.querySelector(`a[href="/docs/VM_DISK_MONITORING#${fragment}"]`)).not.toBeNull();
+ expect(renderGuide('VM_DISK_MONITORING').querySelector(`#${fragment}`)).not.toBeNull();
+ }
+ });
});