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.
Go aialertsdashboarddockerdocker-monitoringgohomelabinfrastructure-monitoringkubernetesmonitoringmspproxmoxproxmox-backup-serverproxmox-mail-gatewayproxmox-veself-hostedtruenastypescriptvspherewebhooks
Explain missing real filesystems without changing guest storage
pulse-triage[bot]137a4354f826
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.mdindex 9152abe354..f16dcf9f53 100644--- a/docs/TROUBLESHOOTING.md+++ b/docs/TROUBLESHOOTING.md@@ -39,6 +39,8 @@ establish safe recovery.[current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).Unknown is not zero, and a working Pulse Agent view does not prove API recovery.+ If only one disk is absent, use [missing-filesystem checks](VM_DISK_MONITORING.md#one-filesystem-is-missing-but-other-disks-have-readings);+ a container-data directory can hold a real disk, independently of backup selection.- **Proxmox data belongs to the wrong host, or healthy jobs look Pending:** use[cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations)or [replication status checks](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing).diff --git a/docs/VM_DISK_MONITORING.md b/docs/VM_DISK_MONITORING.mdindex 0ea02ac9db..233c6cec85 100644--- a/docs/VM_DISK_MONITORING.md+++ b/docs/VM_DISK_MONITORING.md@@ -359,6 +359,55 @@ a backup or a restart to turn an unknown reading into a number. Do not bypass aguest-read pause or widen token access. None of these display states provesthaw or successful workload writes; [Backup safety](#backup-safety) still applies.+If other disks have readings but one filesystem is absent, use+[missing-filesystem checks](#one-filesystem-is-missing-but-other-disks-have-readings)+before treating it as a guest-agent setup failure.++### One filesystem is missing but other disks have readings++A current root-disk reading does not establish that every data filesystem is+monitored. Compare the **same guest and collection source**, using its existing+filesystem view and Pulse's **Filesystems** rows. Keep the observation times;+an old number or recent agent contact does not prove a current disk reading.++- **Attached virtual disk:** its allocated size does not establish a mounted+ filesystem or its used space inside the guest.+- **Separate local filesystem:** ext4, XFS or Btrfs at `/var/lib/containers` or+ `/var/lib/docker` is not a container layer just because of its directory name.+ If Pulse omits it, its usage is unknown in Pulse, not zero.+- **Excluded layer or remote mount:** `overlay`, `tmpfs`, NFS and SMB are excluded+ from filesystem usage. Their absence alone does not establish a missing local+ data disk.++**Pulse v6.6.0 filters `/var/lib/containers` and `/var/lib/docker` by path.**+That can also hide a real local filesystem mounted there, even when the QEMU+Guest Agent returns it. This is separate from an absent or stopped agent;+working readings for other disks do not rule it out. A missing filesystem at+another path can have a different cause.++**Backup inclusion and capacity monitoring are separate.** Excluding a virtual+disk from Proxmox backups does not make its mounted data disposable or explain+its absence from filesystem usage. Leave an intentionally excluded disk+excluded; enabling backups is not a capacity-monitoring repair.++For capacity decisions, use the guest's established filesystem view, or+[current readings from an already linked Pulse Agent](#use-existing-machines-readings-without-changing-the-guest),+with the same guest, filesystem and observation time. An alternative view does+not repair the missing API reading or establish complete monitoring.+**Do not remount or move data, change backup selection, install another agent,+restart services or run guest-agent probes just to make the disk appear.**+If a backup, freeze/thaw or unresponsive guest is involved,+[Backup safety](#backup-safety) takes precedence.++For a report, use facts already available: the running Pulse version, whether+this is the Proxmox API or a Pulse Agent view, which filesystem is missing and+which still have readings. Keep the filesystem type and whether it has its own+device if already known; unknown is valid. Use consistent private aliases for+guest, device and mount names, retaining a relevant standard path such as+`/var/lib/containers` without private suffixes. Do not post full mount tables,+fstab, VM configuration, raw guest-agent responses or Diagnostics exports.+There is no need to collect these facts again if they are in the existing report.+### A missing reading is not an installation diagnosis[Check the reading's context](#current-retained-and-unavailable-disk-readings)diff --git a/docs/release-control/v6/internal/subsystems/frontend-primitives.md b/docs/release-control/v6/internal/subsystems/frontend-primitives.mdindex e7b1a0508a..6e61e9b505 100644--- a/docs/release-control/v6/internal/subsystems/frontend-primitives.md+++ b/docs/release-control/v6/internal/subsystems/frontend-primitives.md@@ -20,6 +20,24 @@## Purpose+### Missing-filesystem help separates real capacity from container layers (28 October 2026)++The existing VM disk guide and Troubleshooting entry distinguish an attached+virtual disk, a real local filesystem under a container-data directory and an+intentionally excluded layer or remote mount. The version-specific v6.6.0 path+filter limitation is not an agent-installation diagnosis or a claim of repair.+Backup inclusion stays separate from capacity collection; deliberately excluded+disks stay excluded. Existing guest or already-linked-agent observations offer+an interim capacity view, not API recovery or complete monitoring.++`missingFilesystemGuide.test.ts` verifies the production Markdown renderer,+entry/target links, exact shipped mirrors, narrow-friendly prose instead of a+new table, source/time/privacy distinctions and the absence of new commands.+No remount, data move, service restart, new agent, guest probe or backup change+is prescribed. Backup safety retains precedence. Source-bound desktop/narrow+Docs interactions and inspected captures remain required; this is Help+maintenance, not a filesystem-admission fix, installed recovery or publication.+### Runtime alert controls describe only supported scope (28 October 2026)Container Runtime rows expose their existing Offline Alerts control, not andiff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.mdindex 9152abe354..f16dcf9f53 100644--- a/frontend-modern/public/docs/TROUBLESHOOTING.md+++ b/frontend-modern/public/docs/TROUBLESHOOTING.md@@ -39,6 +39,8 @@ establish safe recovery.[current, retained and unavailable disks](VM_DISK_MONITORING.md#current-retained-and-unavailable-disk-readings)from [guest memory pressure](TROUBLESHOOTING.md#guest-memory-is-high-but-available-memory-is-plentiful).Unknown is not zero, and a working Pulse Agent view does not prove API recovery.+ If only one disk is absent, use [missing-filesystem checks](VM_DISK_MONITORING.md#one-filesystem-is-missing-but-other-disks-have-readings);+ a container-data directory can hold a real disk, independently of backup selection.- **Proxmox data belongs to the wrong host, or healthy jobs look Pending:** use[cross-installation identity checks](TROUBLESHOOTING.md#monitoring-is-mixed-between-proxmox-installations)or [replication status checks](TROUBLESHOOTING.md#replication-jobs-are-pending-stale-or-missing).diff --git a/frontend-modern/public/docs/VM_DISK_MONITORING.md b/frontend-modern/public/docs/VM_DISK_MONITORING.mdindex 0ea02ac9db..233c6cec85 100644--- a/frontend-modern/public/docs/VM_DISK_MONITORING.md+++ b/frontend-modern/public/docs/VM_DISK_MONITORING.md@@ -359,6 +359,55 @@ a backup or a restart to turn an unknown reading into a number. Do not bypass aguest-read pause or widen token access. None of these display states provesthaw or successful workload writes; [Backup safety](#backup-safety) still applies.+If other disks have readings but one filesystem is absent, use+[missing-filesystem checks](#one-filesystem-is-missing-but-other-disks-have-readings)+before treating it as a guest-agent setup failure.++### One filesystem is missing but other disks have readings++A current root-disk reading does not establish that every data filesystem is+monitored. Compare the **same guest and collection source**, using its existing+filesystem view and Pulse's **Filesystems** rows. Keep the observation times;+an old number or recent agent contact does not prove a current disk reading.++- **Attached virtual disk:** its allocated size does not establish a mounted+ filesystem or its used space inside the guest.+- **Separate local filesystem:** ext4, XFS or Btrfs at `/var/lib/containers` or+ `/var/lib/docker` is not a container layer just because of its directory name.+ If Pulse omits it, its usage is unknown in Pulse, not zero.+- **Excluded layer or remote mount:** `overlay`, `tmpfs`, NFS and SMB are excluded+ from filesystem usage. Their absence alone does not establish a missing local+ data disk.++**Pulse v6.6.0 filters `/var/lib/containers` and `/var/lib/docker` by path.**+That can also hide a real local filesystem mounted there, even when the QEMU+Guest Agent returns it. This is separate from an absent or stopped agent;+working readings for other disks do not rule it out. A missing filesystem at+another path can have a different cause.++**Backup inclusion and capacity monitoring are separate.** Excluding a virtual+disk from Proxmox backups does not make its mounted data disposable or explain+its absence from filesystem usage. Leave an intentionally excluded disk+excluded; enabling backups is not a capacity-monitoring repair.++For capacity decisions, use the guest's established filesystem view, or+[current readings from an already linked Pulse Agent](#use-existing-machines-readings-without-changing-the-guest),+with the same guest, filesystem and observation time. An alternative view does+not repair the missing API reading or establish complete monitoring.+**Do not remount or move data, change backup selection, install another agent,+restart services or run guest-agent probes just to make the disk appear.**+If a backup, freeze/thaw or unresponsive guest is involved,+[Backup safety](#backup-safety) takes precedence.++For a report, use facts already available: the running Pulse version, whether+this is the Proxmox API or a Pulse Agent view, which filesystem is missing and+which still have readings. Keep the filesystem type and whether it has its own+device if already known; unknown is valid. Use consistent private aliases for+guest, device and mount names, retaining a relevant standard path such as+`/var/lib/containers` without private suffixes. Do not post full mount tables,+fstab, VM configuration, raw guest-agent responses or Diagnostics exports.+There is no need to collect these facts again if they are in the existing report.+### A missing reading is not an installation diagnosis[Check the reading's context](#current-retained-and-unavailable-disk-readings)diff --git a/frontend-modern/src/features/docs/__tests__/missingFilesystemGuide.test.ts b/frontend-modern/src/features/docs/__tests__/missingFilesystemGuide.test.tsnew file mode 100644index 0000000000..af7655cdb6--- /dev/null+++ b/frontend-modern/src/features/docs/__tests__/missingFilesystemGuide.test.ts@@ -0,0 +1,105 @@+import { readFileSync } from 'node:fs';+import path from 'node:path';+import { fileURLToPath } from 'node:url';+import { describe, expect, it } from 'vitest';+import { createGuideFixture } from './guideFixture';++const root = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../../../..');+const read = (file: string) => readFileSync(path.join(root, file), 'utf8');+const guide = createGuideFixture((name) => {+ const directory =+ process.env.PULSE_MISSING_FILESYSTEM_GUIDE_INPUT_DIRECTORY ??+ path.join(root, 'frontend-modern/public/docs');+ return readFileSync(path.join(directory, `${name}.md`), 'utf8');+});+const fragment = '#one-filesystem-is-missing-but-other-disks-have-readings';++function section() {+ const heading = guide('VM_DISK_MONITORING').querySelector(fragment);+ expect(heading?.textContent).toBe('One filesystem is missing but other disks have readings');+ const result = document.createElement('section');+ for (let next = heading!.nextElementSibling; next; next = next.nextElementSibling) {+ if (/^H[1-3]$/.test(next.tagName)) break;+ result.appendChild(next.cloneNode(true));+ }+ return result;+}++const prose = (element: Element) => element.textContent!.replace(/\s+/g, ' ').trim();++describe('missing local filesystem guidance', () => {+ it('reaches the shipped explanation from troubleshooting and the general disk context', () => {+ const link = guide('TROUBLESHOOTING').querySelector(+ `a[href="/docs/VM_DISK_MONITORING${fragment}"]`,+ );+ expect(link?.textContent).toBe('missing-filesystem checks');+ const disk = guide('VM_DISK_MONITORING');+ expect(disk.querySelector(`a[href="${fragment}"]`)?.textContent).toBe(+ 'missing-filesystem checks',+ );+ expect(section()).toBeTruthy();+ for (const name of ['VM_DISK_MONITORING', 'TROUBLESHOOTING']) {+ expect(read(`frontend-modern/public/docs/${name}.md`)).toBe(read(`docs/${name}.md`));+ }+ });++ it('separates allocated capacity, real local filesystems and intentionally excluded layers', () => {+ const content = section();+ const observations = [...content.querySelectorAll('ul > li')];+ expect(observations).toHaveLength(3);+ expect(observations.map((item) => item.querySelector('strong')?.textContent)).toEqual([+ 'Attached virtual disk:',+ 'Separate local filesystem:',+ 'Excluded layer or remote mount:',+ ]);+ expect(prose(observations[0])).toContain('does not establish a mounted filesystem');+ expect(prose(observations[1])).toContain('not a container layer just because');+ expect(prose(observations[1])).toContain('unknown in Pulse, not zero');+ expect(prose(observations[2])).toContain('overlay, tmpfs, NFS and SMB');+ // Avoid another horizontally scrolling table in the current Docs reader.+ expect(content.querySelector('table')).toBeNull();+ const text = prose(content);+ expect(text).toContain('Pulse v6.6.0 filters /var/lib/containers and /var/lib/docker by path');+ expect(text).toContain('even when the QEMU Guest Agent returns it');+ expect(text).toContain('A missing filesystem at another path can have a different cause');+ expect(text).toContain('Backup inclusion and capacity monitoring are separate');+ expect(text).toContain('Leave an intentionally excluded disk excluded');+ expect(text).toContain('enabling backups is not a capacity-monitoring repair');+ });++ it('offers an existing capacity view without remounting, agent installation or backup changes', () => {+ const content = section();+ const text = prose(content);+ for (const distinction of [+ 'same guest and collection source',+ "use the guest's established filesystem view",+ 'does not repair the missing API reading or establish complete monitoring',+ 'Do not remount or move data, change backup selection, install another agent',+ 'restart services or run guest-agent probes',+ 'Backup safety takes precedence',+ ]) {+ expect(text).toContain(distinction);+ }+ for (const target of ['use-existing-machines-readings-without-changing-the-guest', 'backup-safety']) {+ expect(content.querySelector(`a[href="#${target}"]`)).not.toBeNull();+ expect(guide('VM_DISK_MONITORING').querySelector(`#${target}`)).not.toBeNull();+ }+ expect(content.querySelector('pre')).toBeNull();+ });++ it('uses supplied source-specific facts and preserves private mount and configuration evidence', () => {+ const text = prose(section());+ for (const boundary of [+ 'use facts already available',+ 'whether this is the Proxmox API or a Pulse Agent view',+ 'which filesystem is missing and which still have readings',+ 'if already known; unknown is valid',+ 'consistent private aliases',+ 'without private suffixes',+ 'Do not post full mount tables, fstab, VM configuration, raw guest-agent responses or Diagnostics exports',+ 'no need to collect these facts again if they are in the existing report',+ ]) {+ expect(text).toContain(boundary);+ }+ });+});