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.

Explain missing real filesystems without changing guest storage

pulse-triage[bot]137a4354f826
diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md
index 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.md
index 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 a
guest-read pause or widen token access. None of these display states proves
thaw 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.md
index 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 an
diff --git a/frontend-modern/public/docs/TROUBLESHOOTING.md b/frontend-modern/public/docs/TROUBLESHOOTING.md
index 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.md
index 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 a
guest-read pause or widen token access. None of these display states proves
thaw 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.ts
new file mode 100644
index 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);
+ }
+ });
+});