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(); + } + }); });