Skip to content

The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu

Harden external-volume launchd diagnostics

Justin D'Souza112d9e1542d5
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
index 718d49dc..0c86fb4e 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go
@@ -82,16 +82,20 @@ func launchAgentVolumeCheck(vol service.LaunchAgentVolume) Check {
Message: "LaunchAgents is on the startup volume", Evidence: "launch_agents_startup_volume"}
}
if vol.StagingDir == "" {
+ detail := "no private directory on the startup volume was usable"
+ if vol.StagingError != "" {
+ detail += ": " + vol.StagingError
+ }
return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusFail, Severity: SeverityHigh,
- Message: vol.Reason + ", so launchd refuses to bootstrap Beacon's LaunchAgents from it, and no private " +
- "directory on the startup volume was found to bootstrap a copy from",
+ Message: vol.Reason + ", so launchd refuses to bootstrap Beacon's LaunchAgents from it, and " + detail,
Evidence: "launch_agents_external_volume_unstaged",
Action: "install with --no-start, copy the plists from " + vol.PlistDir + " into a private directory on the " +
"startup volume, and run `launchctl bootstrap gui/$(id -u) <copied plist>` for each"}
}
- return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusWarn, Severity: SeverityLow,
+ return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusWarn, Severity: SeverityMedium,
Message: vol.Reason + ", which launchd will not bootstrap LaunchAgents from; Beacon bootstraps copies staged in " +
- vol.StagingDir + " instead. If the collector is not running after a restart or login, repair the install to restage them",
+ vol.StagingDir + " instead for this login session. Automatic loading after logout or restart is not guaranteed; " +
+ "if the collector is not running, repair the install to restage the jobs",
Evidence: "launch_agents_external_volume_staged",
Action: "beacon endpoint repair --user"}
}
diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
index 3a1c3f76..ab26cae5 100644
--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go
@@ -203,19 +203,23 @@ func TestLaunchAgentVolumeCheck(t *testing.T) {
StagingDir: "/var/folders/xx/T/beacon-launchd-502",
Reason: "/Volumes/Ext/Library/LaunchAgents is on a different volume than /Users",
})
- if staged.Status != StatusWarn || staged.Evidence != "launch_agents_external_volume_staged" ||
+ if staged.Status != StatusWarn || staged.Severity != SeverityMedium ||
+ staged.Evidence != "launch_agents_external_volume_staged" ||
staged.Action != "beacon endpoint repair --user" ||
- !strings.Contains(staged.Message, "/var/folders/xx/T/beacon-launchd-502") {
+ !strings.Contains(staged.Message, "/var/folders/xx/T/beacon-launchd-502") ||
+ !strings.Contains(staged.Message, "not guaranteed") {
t.Fatalf("staged external-volume check = %#v", staged)
}
unstaged := launchAgentVolumeCheck(service.LaunchAgentVolume{
- PlistDir: "/Volumes/Ext/Library/LaunchAgents",
- External: true,
- Reason: "/Volumes/Ext/Library/LaunchAgents is under /Volumes",
+ PlistDir: "/Volumes/Ext/Library/LaunchAgents",
+ External: true,
+ StagingError: "/private/tmp/beacon-launchd-502 is mode 770",
+ Reason: "/Volumes/Ext/Library/LaunchAgents is under /Volumes",
})
if unstaged.Status != StatusFail || unstaged.Evidence != "launch_agents_external_volume_unstaged" ||
- !strings.Contains(unstaged.Action, "--no-start") || !strings.Contains(unstaged.Action, "launchctl bootstrap gui/") {
+ !strings.Contains(unstaged.Action, "--no-start") || !strings.Contains(unstaged.Action, "launchctl bootstrap gui/") ||
+ !strings.Contains(unstaged.Message, "mode 770") {
t.Fatalf("unstaged external-volume check = %#v", unstaged)
}
}
diff --git a/cli/beacon/internal/endpoint/service/launchd_volume.go b/cli/beacon/internal/endpoint/service/launchd_volume.go
index 496c4286..452eef1d 100644
--- a/cli/beacon/internal/endpoint/service/launchd_volume.go
+++ b/cli/beacon/internal/endpoint/service/launchd_volume.go
@@ -44,6 +44,8 @@ type LaunchAgentVolume struct {
// StagingDir is the private startup-volume directory the plist is bootstrapped from when
// External is true. Empty when External is false, or when no usable location was found.
StagingDir string `json:"staging_dir,omitempty"`
+ // StagingError explains why none of the candidate startup-volume directories was usable.
+ StagingError string `json:"staging_error,omitempty"`
// Reason says how External was decided, for diagnostics.
Reason string `json:"reason,omitempty"`
}
@@ -70,20 +72,35 @@ func InspectLaunchAgentVolume(plistPath string) LaunchAgentVolume {
if !vol.External {
return vol
}
+ var stagingErrors []string
for _, base := range launchdStagingBases() {
if strings.TrimSpace(base) == "" {
continue
}
if bootErr == nil {
if id, err := launchdVolumeID(base); err != nil || id != bootID {
+ if err != nil {
+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: cannot inspect volume: %v", base, err))
+ } else {
+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: not on the startup volume", base))
+ }
continue
}
} else if underVolumes(base) {
+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: under /Volumes", base))
continue
}
- vol.StagingDir = filepath.Join(base, launchdStagingDirName())
+ candidate := filepath.Join(base, launchdStagingDirName())
+ if err := probeLaunchdStagingDir(candidate); err != nil {
+ stagingErrors = append(stagingErrors, fmt.Sprintf("%s: %v", candidate, err))
+ continue
+ }
+ vol.StagingDir = candidate
break
}
+ if vol.StagingDir == "" {
+ vol.StagingError = strings.Join(stagingErrors, "; ")
+ }
return vol
}
@@ -113,7 +130,11 @@ func launchdBootstrapPath(domain, plistPath string) (string, string) {
return plistPath, ""
}
if vol.StagingDir == "" {
- return plistPath, externalVolumeNote(domain, vol, "", errors.New("no private directory on the startup volume was found"))
+ err := errors.New("no usable private directory on the startup volume was found")
+ if vol.StagingError != "" {
+ err = errors.New(vol.StagingError)
+ }
+ return plistPath, externalVolumeNote(domain, vol, "", err)
}
staged, err := stageLaunchdPlist(plistPath, vol.StagingDir)
if err != nil {
@@ -132,10 +153,35 @@ func externalVolumeNote(domain string, vol LaunchAgentVolume, staged string, sta
} else {
fmt.Fprintf(&b, " Beacon bootstrapped a copy staged at %s, and launchd refused that too.", staged)
}
- fmt.Fprintf(&b, " To load it by hand: install with --no-start, copy the plist from %s into a private directory on the startup volume (mkdir -p -m 700 \"$TMPDIR/beacon-launchd\"), then run `launchctl bootstrap %s <copied plist>`.", vol.PlistDir, domain)
+ fmt.Fprintf(&b, " To load it by hand: install with --no-start, copy the plist from %s into a private directory on the startup volume (`mkdir -p \"$TMPDIR/beacon-launchd\" && chmod 700 \"$TMPDIR/beacon-launchd\"`), then run `launchctl bootstrap %s <copied plist>`.", vol.PlistDir, domain)
return b.String()
}
+// probeLaunchdStagingDir verifies the same ownership, mode and write requirements used by staging.
+// It removes an empty directory it created so inspection does not leave state behind.
+func probeLaunchdStagingDir(dir string) error {
+ if err := os.Mkdir(dir, 0o700); err != nil {
+ if !os.IsExist(err) {
+ return err
+ }
+ } else {
+ defer os.Remove(dir)
+ }
+ if err := checkPrivateStagingDir(dir); err != nil {
+ return err
+ }
+ probe, err := os.CreateTemp(dir, ".probe-*")
+ if err != nil {
+ return err
+ }
+ probePath := probe.Name()
+ if err := probe.Close(); err != nil {
+ _ = os.Remove(probePath)
+ return err
+ }
+ return os.Remove(probePath)
+}
+
// stageLaunchdPlist copies plistPath into stagingDir under the same name and returns the copy's path.
//
// The directory is a fixed name in a temp directory, so it has to be one this user owns and nobody
diff --git a/cli/beacon/internal/endpoint/service/launchd_volume_test.go b/cli/beacon/internal/endpoint/service/launchd_volume_test.go
index d2d7c523..5b84c590 100644
--- a/cli/beacon/internal/endpoint/service/launchd_volume_test.go
+++ b/cli/beacon/internal/endpoint/service/launchd_volume_test.go
@@ -122,6 +122,12 @@ func TestInspectLaunchAgentVolumeFlagsPlistOffTheStartupVolume(t *testing.T) {
if !vol.External {
t.Fatalf("plist on the external volume was not flagged: %#v", vol)
}
+ if !testenv.HasPOSIXFileModes() {
+ if vol.StagingDir != "" || vol.StagingError == "" {
+ t.Fatalf("host without POSIX modes should reject private staging: %#v", vol)
+ }
+ return
+ }
if vol.StagingDir != f.staging {
t.Fatalf("staging dir = %q, want %q on the startup volume", vol.StagingDir, f.staging)
}
@@ -130,6 +136,44 @@ func TestInspectLaunchAgentVolumeFlagsPlistOffTheStartupVolume(t *testing.T) {
}
}
+func TestInspectLaunchAgentVolumeRejectsAnUnsafeStagingDirectory(t *testing.T) {
+ testenv.RequirePOSIXFileModes(t)
+ f := newVolumeFixture(t)
+ if err := os.Mkdir(f.staging, 0o770); err != nil {
+ t.Fatal(err)
+ }
+
+ vol := InspectLaunchAgentVolume(f.externalPlist(t, UserLabel))
+ if !vol.External || vol.StagingDir != "" {
+ t.Fatalf("unsafe staging directory reported usable: %#v", vol)
+ }
+ if !strings.Contains(vol.StagingError, "must not be accessible to other users") {
+ t.Fatalf("staging error does not explain unsafe permissions: %#v", vol)
+ }
+}
+
+func TestInspectLaunchAgentVolumeFallsBackFromAnUnsafeStagingDirectory(t *testing.T) {
+ testenv.RequirePOSIXFileModes(t)
+ f := newVolumeFixture(t)
+ if err := os.Mkdir(f.staging, 0o770); err != nil {
+ t.Fatal(err)
+ }
+ fallbackBase := filepath.Join(f.boot, "private-tmp")
+ if err := os.Mkdir(fallbackBase, 0o777); err != nil {
+ t.Fatal(err)
+ }
+ primaryBase := filepath.Dir(f.staging)
+ oldBases := launchdStagingBases
+ launchdStagingBases = func() []string { return []string{primaryBase, fallbackBase} }
+ t.Cleanup(func() { launchdStagingBases = oldBases })
+
+ vol := InspectLaunchAgentVolume(f.externalPlist(t, UserLabel))
+ want := filepath.Join(fallbackBase, launchdStagingDirName())
+ if vol.StagingDir != want || vol.StagingError != "" {
+ t.Fatalf("fallback staging directory = %#v, want %s", vol, want)
+ }
+}
+
func TestInspectLaunchAgentVolumeLeavesStartupVolumeHomesAlone(t *testing.T) {
f := newVolumeFixture(t)
vol := InspectLaunchAgentVolume(f.bootPlist(t, UserLabel))
diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdx
index 1ef006de..b4ac0cf7 100644
--- a/docs/cli/endpoint-paths.mdx
+++ b/docs/cli/endpoint-paths.mdx
@@ -40,7 +40,7 @@ The Beacon forwarder started by `beacon endpoint connect` is a second, resident
The scheduled inventory job is a third, one-shot unit that `beacon endpoint install` writes in both modes and the package postinstall reconciles on every upgrade: `/Library/LaunchDaemons/com.beacon.endpoint.inventory.plist` or `~/Library/LaunchAgents/com.beacon.endpoint.inventory.plist` on macOS, `beacon-inventory.timer` plus `beacon-inventory.service` under `/etc/systemd/system` or `~/.config/systemd/user` on Linux. It writes `inventory_state.jsonl` and its `inventory-state.json` state file beside the runtime log. Like the forwarder it is not offered in supervised mode; run `beacon endpoint inventory heartbeat --scheduled` from your own scheduler there.
-On macOS, when `~/Library/LaunchAgents` is on a volume other than the startup volume, such as a home directory on an external disk, launchd refuses to bootstrap plists from it. Beacon then bootstraps each user LaunchAgent from a copy staged in `$TMPDIR/beacon-launchd-<uid>`, falling back to `/private/tmp/beacon-launchd-<uid>`. The canonical plist stays in `~/Library/LaunchAgents`. See [Home directory on an external volume](/platforms/macos#home-directory-on-an-external-volume).
+On macOS, when `~/Library/LaunchAgents` is on a volume other than the startup volume, such as a home directory on an external disk, launchd refuses to bootstrap plists from it. Beacon then bootstraps each user LaunchAgent for the current login session from a copy staged in `$TMPDIR/beacon-launchd-<uid>`, falling back to `/private/tmp/beacon-launchd-<uid>`. The canonical plist stays in `~/Library/LaunchAgents`; automatic loading after logout or restart is not guaranteed for this layout. See [Home directory on an external volume](/platforms/macos#home-directory-on-an-external-volume).
Windows has no unit file to point at: the service definition lives in the registry, so that is what `beacon endpoint status` reports where the other platforms report a path. And there is no counterpart to `systemctl --user` or launchd's per-user domain, so a Windows user-mode install always gets the supervised collector. See [Windows install](/platforms/windows#user-mode-install).
diff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdx
index e41f5d4e..2abe7617 100644
--- a/docs/platforms/macos.mdx
+++ b/docs/platforms/macos.mdx
@@ -72,13 +72,14 @@ beacon endpoint doctor --fix
launchd will not bootstrap a LaunchAgent whose plist is on a volume other than the startup volume. When your home directory is on an external disk (`/Volumes/<disk>`), `launchctl bootstrap gui/<uid> ~/Library/LaunchAgents/<label>.plist` fails with `Bootstrap failed: 5: Input/output error`, even with ownership enabled on the volume.
-A user-mode install handles this itself. Beacon still writes the canonical plists to `~/Library/LaunchAgents`, but when that directory is on a different volume from `/Users`, it copies each plist into a private directory on the startup volume and bootstraps the copy instead. That directory is `$TMPDIR/beacon-launchd-<uid>`, with `/private/tmp/beacon-launchd-<uid>` as a fallback, and it must be owned by you with mode `0700`. This applies to the collector, the scheduled inventory job, and the managed forwarder. The program, its config, and the logs stay where they are, and a home on the startup volume is bootstrapped in place as before. `launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"` shows the staged path.
+A user-mode install handles the current login session itself. Beacon still writes the canonical plists to `~/Library/LaunchAgents`, but when that directory is on a different volume from `/Users`, it copies each plist into a private directory on the startup volume and bootstraps the copy instead. That directory is `$TMPDIR/beacon-launchd-<uid>`, with `/private/tmp/beacon-launchd-<uid>` as a fallback, and it must be owned by you with mode `0700`. This applies to the collector, the scheduled inventory job, and the managed forwarder. The program, its config, and the logs stay where they are, and a home on the startup volume is bootstrapped in place as before. `launchctl print "gui/$(id -u)/com.beacon.endpoint.collector.user"` shows the staged path.
-`beacon endpoint doctor` reports this layout as `launch_agents_volume`. If the collector is not running after a restart or login, run `beacon endpoint repair --user`, which stages fresh copies and bootstraps them again. If Beacon cannot stage the copies, doctor reports a failure. In that case, bootstrap them by hand:
+The explicit bootstrap registration belongs to the current launchd login domain. Beacon cannot guarantee that launchd will reload the canonical external-volume plists automatically after logout or restart. `beacon endpoint doctor` therefore reports this layout as a medium-severity `launch_agents_volume` warning even when staging works. If the collector is not running after a restart or login, run `beacon endpoint repair --user`, which stages fresh copies and bootstraps them again. If Beacon cannot safely create and write the staging directory, doctor reports a failure with the rejected path and reason. In that case, bootstrap the plists by hand:
```bash title="Manual bootstrap from the startup volume"
beacon endpoint install --user --no-start
-mkdir -p -m 700 "$TMPDIR/beacon-launchd"
+mkdir -p "$TMPDIR/beacon-launchd"
+chmod 700 "$TMPDIR/beacon-launchd"
for label in com.beacon.endpoint.collector.user com.beacon.endpoint.inventory; do
cp "$HOME/Library/LaunchAgents/$label.plist" "$TMPDIR/beacon-launchd/"
launchctl bootout "gui/$(id -u)/$label" 2>/dev/null || true