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.

Hide macOS Time Machine mounts from agent disk inventory

rcourtman1b964ff5aaff
diff --git a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
index ad929610dc..55adadbad5 100644
--- a/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
+++ b/docs/release-control/v6/internal/subsystems/agent-lifecycle.md
@@ -4186,6 +4186,13 @@ explicitly mapped administrator reaches the lifecycle handlers.
`TestGuardedDiskUsagePublishesAfterRetiringProbe` controls the retirement
lock to prove publication cannot get ahead of removal. The adjacent stuck
mount tests retain sharing, recovery, timeout and cancellation coverage.
+ Mounts whose options carry macOS `nobrowse` (APFS companion volumes,
+ simulator runtimes, the Time Machine backup image and its per-backup
+ snapshots) are platform plumbing and are skipped before the usage syscall
+ unless the operator explicitly includes them; `/Volumes/.timemachine/`
+ is also a shared special mountpoint so the server hides snapshot rows that
+ older agents still report. `TestCollectDisksSkipsMacOSHiddenMountsBeforeUsage`
+ pins both the skip and the explicit-include override.
4. Keep host-agent test hooks, command-client factories, and timing overrides
instance-scoped under `internal/hostagent/agent.go`; lifecycle-owned
registration and update paths must not depend on package-global mutable test
diff --git a/internal/hostmetrics/collector.go b/internal/hostmetrics/collector.go
index 072be6108f..4f7ee9c9d6 100644
--- a/internal/hostmetrics/collector.go
+++ b/internal/hostmetrics/collector.go
@@ -394,6 +394,7 @@ func collectDisksWithIncludes(ctx context.Context, diskExclude, diskInclude []st
explicitlyIncluded := fsfilters.MatchesDiskInclude(part.Device, part.Mountpoint, diskInclude)
isZFS := strings.EqualFold(part.Fstype, "zfs") || strings.EqualFold(part.Fstype, "fuse.zfs")
+ hiddenSystemMount := fsfilters.IsHiddenSystemMount(part.Opts)
// Type- and mountpoint-based skips need no usage data. Deciding them
// before the usage syscall keeps mounts that would be discarded
@@ -401,6 +402,9 @@ func collectDisksWithIncludes(ctx context.Context, diskExclude, diskInclude []st
// collector inside statfs. ZFS stays after usage collection because
// its datasets are aggregated before this filter applies.
if !isZFS && !explicitlyIncluded {
+ if hiddenSystemMount {
+ continue
+ }
if shouldSkip, _ := fsfilters.ShouldSkipFilesystem(part.Fstype, part.Mountpoint, 0, 0); shouldSkip {
continue
}
@@ -445,6 +449,7 @@ func collectDisksWithIncludes(ctx context.Context, diskExclude, diskInclude []st
// - Container overlay paths (Docker/Podman layers on ZFS, including TrueNAS .ix-apps)
// See issues #505, #690, #718, #790.
automaticallyFiltered, _ := fsfilters.ShouldSkipFilesystem(part.Fstype, part.Mountpoint, usage.Total, usage.Used)
+ automaticallyFiltered = automaticallyFiltered || hiddenSystemMount
if automaticallyFiltered && !explicitlyIncluded {
continue
}
diff --git a/internal/hostmetrics/collector_test.go b/internal/hostmetrics/collector_test.go
index 5fb4b39e50..af35688400 100644
--- a/internal/hostmetrics/collector_test.go
+++ b/internal/hostmetrics/collector_test.go
@@ -198,6 +198,59 @@ func TestCollectDisksExcludesFreeBSDFdescfsBeforeUsage(t *testing.T) {
}
}
+// A Mac backing up to a network Time Machine destination mounts the backup
+// disk image plus one read-only snapshot per retained backup. macOS marks all
+// of them nobrowse; reporting them buried the real disks under rows whose
+// capacity is the sparse bundle's ceiling, not the destination's space.
+func TestCollectDisksSkipsMacOSHiddenMountsBeforeUsage(t *testing.T) {
+ origPartitions := diskPartitions
+ origUsage := diskUsage
+ t.Cleanup(func() {
+ diskPartitions = origPartitions
+ diskUsage = origUsage
+ })
+
+ const backupImage = "/Volumes/Backups of RICHARD-MAC-MINI"
+ diskPartitions = func(context.Context, bool) ([]godisk.PartitionStat, error) {
+ return []godisk.PartitionStat{
+ {Device: "/dev/disk3s1s1", Mountpoint: "/", Fstype: "apfs", Opts: []string{"ro", "journaled", "local"}},
+ {Device: "/dev/disk7s1", Mountpoint: "/Volumes/Development", Fstype: "apfs", Opts: []string{"rw", "nodev", "nosuid", "journaled", "local", "noowners"}},
+ {Device: "/dev/disk11s1", Mountpoint: backupImage, Fstype: "apfs", Opts: []string{"rw", "nodev", "nosuid", "nobrowse", "journaled", "local"}},
+ {Device: "com.apple.TimeMachine.2026-10-25-122503.backup@/dev/disk11s1", Mountpoint: "/Volumes/.timemachine/5D0A488B/2026-10-25-122503.backup", Fstype: "apfs", Opts: []string{"ro", "nodev", "nosuid", "nobrowse", "journaled", "local"}},
+ }, nil
+ }
+
+ usageCalls := make([]string, 0, 2)
+ diskUsage = func(_ context.Context, path string) (*godisk.UsageStat, error) {
+ usageCalls = append(usageCalls, path)
+ return &godisk.UsageStat{Path: path, Total: 1000, Used: 400, Free: 600, UsedPercent: 40}, nil
+ }
+
+ disks := collectDisks(context.Background(), nil)
+ got := make([]string, 0, len(disks))
+ for _, disk := range disks {
+ got = append(got, disk.Mountpoint)
+ }
+ want := []string{"/", "/Volumes/Development"}
+ if !reflect.DeepEqual(got, want) {
+ t.Fatalf("reported mounts = %v, want %v", got, want)
+ }
+ if !reflect.DeepEqual(usageCalls, want) {
+ t.Fatalf("disk usage queried for %v, want only %v", usageCalls, want)
+ }
+
+ disks = collectDisksWithIncludes(context.Background(), nil, []string{backupImage})
+ found := false
+ for _, disk := range disks {
+ if disk.Mountpoint == backupImage {
+ found = true
+ }
+ }
+ if !found {
+ t.Fatalf("explicitly included hidden mount was dropped: %+v", disks)
+ }
+}
+
func TestCollectDisksIncludesExplicitTmpfsMount(t *testing.T) {
origPartitions := diskPartitions
origUsage := diskUsage
diff --git a/pkg/fsfilters/filters.go b/pkg/fsfilters/filters.go
index 8a9d966d29..7023b480e9 100644
--- a/pkg/fsfilters/filters.go
+++ b/pkg/fsfilters/filters.go
@@ -101,6 +101,7 @@ var specialMountPrefixes = []string{
"/snap",
"/System/Volumes/", // macOS APFS system/data/preboot/update companion volumes
"/Library/Developer/CoreSimulator/Volumes/", // Xcode simulator runtime disk images
+ "/Volumes/.timemachine/", // macOS Time Machine snapshot and destination mounts
}
// specialMountpoints are exact mountpoints that represent platform plumbing
@@ -227,6 +228,20 @@ func ShouldSkipFilesystem(fsType, mountpoint string, totalBytes, usedBytes uint6
return len(reasons) > 0, reasons
}
+// IsHiddenSystemMount reports whether the mount options mark the filesystem
+// as not a path to user data. macOS sets nobrowse (MNT_DONTBROWSE) on APFS
+// companion volumes, simulator runtimes and every Time Machine mount,
+// including the backup disk image whose advertised capacity is the sparse
+// bundle's ceiling rather than the destination's real space.
+func IsHiddenSystemMount(opts []string) bool {
+ for _, opt := range opts {
+ if opt == "nobrowse" {
+ return true
+ }
+ }
+ return false
+}
+
// MatchesUserExclude checks if a mountpoint matches any user-defined exclusion patterns.
// Patterns can be:
// - Exact paths: "/mnt/backup" matches only "/mnt/backup"
diff --git a/pkg/fsfilters/filters_test.go b/pkg/fsfilters/filters_test.go
index 985c74ea0c..76d18f13e5 100644
--- a/pkg/fsfilters/filters_test.go
+++ b/pkg/fsfilters/filters_test.go
@@ -205,6 +205,8 @@ func TestShouldSkipFilesystem(t *testing.T) {
{"macos preboot companion volume", "apfs", "/System/Volumes/Preboot", 245107195904, 213573853184, true},
{"macos simulator runtime volume", "apfs", "/Library/Developer/CoreSimulator/Volumes/iOS_23E254a", 18058575872, 17593331712, true},
{"macos app translocation volume", "apfs", "/private/var/folders/xy/random/T/AppTranslocation/2A9C/d/Pulse.app", 245107195904, 221809991680, true},
+ {"macos time machine backup snapshot", "apfs", "/Volumes/.timemachine/5D0A488B-87DC-4532-96F4-FA1E0BFDD0F4/2026-10-25-122503.backup", 16090000000000, 352000000000, true},
+ {"macos time machine network destination", "apfs", "/Volumes/.timemachine/tower/6DBDE5B4-8924-4042-B6EE-4A5C68074C46/MacTimeMachine", 1649000000000, 403000000000, true},
// Regular filesystems that should NOT be skipped
{"ext4 root", "ext4", "/", 100 * 1024 * 1024 * 1024, 50 * 1024 * 1024 * 1024, false},
@@ -397,3 +399,27 @@ func TestIsNonPhysicalDiskIODevice(t *testing.T) {
}
}
}
+
+func TestIsHiddenSystemMount(t *testing.T) {
+ hidden := [][]string{
+ {"local", "nodev", "nosuid", "journaled", "nobrowse"},
+ {"nobrowse"},
+ }
+ for _, opts := range hidden {
+ if !IsHiddenSystemMount(opts) {
+ t.Errorf("IsHiddenSystemMount(%v) = false, want true", opts)
+ }
+ }
+
+ visible := [][]string{
+ nil,
+ {"rw", "relatime"},
+ {"local", "nodev", "nosuid", "journaled", "noowners"},
+ {"nobrowsex"},
+ }
+ for _, opts := range visible {
+ if IsHiddenSystemMount(opts) {
+ t.Errorf("IsHiddenSystemMount(%v) = true, want false", opts)
+ }
+ }
+}
diff --git a/pkg/fsfilters/mount_boundary_test.go b/pkg/fsfilters/mount_boundary_test.go
index 5de61899a6..5a92f1d288 100644
--- a/pkg/fsfilters/mount_boundary_test.go
+++ b/pkg/fsfilters/mount_boundary_test.go
@@ -11,7 +11,7 @@ func TestSystemMountFiltersRespectDirectoryBoundaries(t *testing.T) {
for _, directory := range []string{
"/dev", "/proc", "/sys", "/run", "/var/run", "/var/lib/docker",
"/var/lib/containers", "/snap", "/System/Volumes",
- "/Library/Developer/CoreSimulator/Volumes",
+ "/Library/Developer/CoreSimulator/Volumes", "/Volumes/.timemachine",
} {
t.Run(directory, func(t *testing.T) {
for _, path := range []string{directory, directory + "/", directory + "/child/mount"} {