The cross-harness, self-improving memory layer for AI agents. Join our community: https://discord.com/invite/zdNChS2fBu
Go agent-ai-cliagent-harnessesagent-securitybrowser-extensionciclaude-codecloudcodexcursordetection-engineeringjevknowledge-basememorymobile-device-managementobservabilitysecuritysecurity-information-and-event-managementsecurity-toolstelemetrytraces
Bootstrap user LaunchAgents from a staged copy when HOME is on an external volume
Claude76225641c335
diff --git a/cli/beacon/cmd/endpoint_diagnostics.go b/cli/beacon/cmd/endpoint_diagnostics.goindex 03b20e78..5e47a08e 100644--- a/cli/beacon/cmd/endpoint_diagnostics.go+++ b/cli/beacon/cmd/endpoint_diagnostics.go@@ -1556,6 +1556,13 @@ func planDoctorFixes(result doctorResult, status lifecycle.Status) doctorFixPlan// Nothing here is Beacon's to repair: the sandbox mode is the operator's choice in dsh, and// widening it on their behalf would be the wrong fix even if doctor could. Reported as a// skip so --fix does not read as having found nothing.+ // A LaunchAgents directory on an external volume is a layout, not damage: when Beacon can+ // stage the plists (warn) the install already works and there is nothing to repair; when it+ // cannot (fail) the remedy is the manual bootstrap in the check's action.+ case "launch_agents_volume":+ if check.Status == diagnostics.StatusFail {+ addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})+ }case "dsh_hook_capture":addSkip(plannedAction{Action: "manual_fix", Target: check.Target, Message: check.Action})}diff --git a/cli/beacon/cmd/endpoint_test.go b/cli/beacon/cmd/endpoint_test.goindex 1b058339..1045d052 100644--- a/cli/beacon/cmd/endpoint_test.go+++ b/cli/beacon/cmd/endpoint_test.go@@ -2022,6 +2022,27 @@ func TestPlanDoctorFixesDoesNotTreatMissingEventAsAppliedFix(t *testing.T) {}}+// An external-volume home that Beacon can stage is informational, so --fix must not repair it; one it+// cannot stage is skipped with the manual bootstrap as the message (#639).+func TestPlanDoctorFixesTreatsLaunchAgentsVolumeAsManual(t *testing.T) {+ status := lifecycle.Status{RuntimeLog: lifecycle.RuntimeLogSource{EffectiveUserMode: true}}+ staged := planDoctorFixes(doctorResult{Checks: []diagnostics.Check{+ {Name: "launch_agents_volume", Target: "/Volumes/Ext/Library/LaunchAgents", Status: diagnostics.StatusWarn,+ Evidence: "launch_agents_external_volume_staged", Action: "beacon endpoint repair --user"},+ }}, status)+ if len(staged.Fixes) != 0 || len(staged.Skipped) != 0 {+ t.Fatalf("a staged external-volume home needs no fix: %#v", staged)+ }+ unstaged := planDoctorFixes(doctorResult{Checks: []diagnostics.Check{+ {Name: "launch_agents_volume", Target: "/Volumes/Ext/Library/LaunchAgents", Status: diagnostics.StatusFail,+ Evidence: "launch_agents_external_volume_unstaged", Action: "install with --no-start, then launchctl bootstrap"},+ }}, status)+ if len(unstaged.Fixes) != 0 || len(unstaged.Skipped) != 1 || unstaged.Skipped[0].Action != "manual_fix" ||+ !strings.Contains(unstaged.Skipped[0].Message, "--no-start") {+ t.Fatalf("an unstaged external-volume home should be a manual skip: %#v", unstaged)+ }+}+func TestApplyDoctorFixesContinuesAfterCollectorRepairFailure(t *testing.T) {home := t.TempDir()testenv.SetHome(t, home)diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics.goindex 894829e2..718d49dc 100644--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics.go+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics.go@@ -51,6 +51,11 @@ func Run(cfg endpointconfig.Config) []Check {case service.KindLaunchd:if path, err := mgr.UnitPath(); err == nil {checks = append(checks, checkFile("launchd_plist", path, true))+ // A home directory on an external volume is the one layout where the plist being+ // present says nothing about whether launchd will load it (#639).+ if cfg.UserMode {+ checks = append(checks, launchAgentVolumeCheck(service.InspectLaunchAgentVolume(path)))+ }}case service.KindSystemd:if path, err := mgr.UnitPath(); err == nil {@@ -66,6 +71,31 @@ func Run(cfg endpointconfig.Config) []Check {return checks}+// launchAgentVolumeCheck reports a LaunchAgents directory off the startup volume. launchd refuses to+// bootstrap plists from there ("Bootstrap failed: 5: Input/output error"), so Beacon bootstraps a+// staged copy on the startup volume instead. That works for the running session, but it is a+// layout worth naming: whether launchd's own login scan loads the canonical plist is not something+// Beacon can see, and a collector missing after a restart is fixed by a repair, which restages it.+func launchAgentVolumeCheck(vol service.LaunchAgentVolume) Check {+ if !vol.External {+ return Check{Name: "launch_agents_volume", Target: vol.PlistDir, Status: StatusOK, Severity: SeverityInfo,+ Message: "LaunchAgents is on the startup volume", Evidence: "launch_agents_startup_volume"}+ }+ if vol.StagingDir == "" {+ 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",+ 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,+ 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",+ Evidence: "launch_agents_external_volume_staged",+ Action: "beacon endpoint repair --user"}+}+func lingerCheck() Check {u, err := user.Current()if err != nil || u.Username == "" {diff --git a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.goindex 97cbc7d3..3a1c3f76 100644--- a/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go+++ b/cli/beacon/internal/endpoint/diagnostics/diagnostics_test.go@@ -4,6 +4,7 @@ import ("os""os/user""path/filepath"+ "strings""testing"endpointconfig "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/endpoint/config"@@ -189,3 +190,32 @@ func TestLingerCheckOffersTheSharedRemediation(t *testing.T) {t.Errorf("doctor action = %q, want the shared remediation %q", check.Action, want)}}++func TestLaunchAgentVolumeCheck(t *testing.T) {+ onBoot := launchAgentVolumeCheck(service.LaunchAgentVolume{PlistDir: "/Users/test/Library/LaunchAgents"})+ if onBoot.Status != StatusOK || onBoot.Evidence != "launch_agents_startup_volume" {+ t.Fatalf("startup-volume check = %#v", onBoot)+ }++ staged := launchAgentVolumeCheck(service.LaunchAgentVolume{+ PlistDir: "/Volumes/Ext/Library/LaunchAgents",+ External: true,+ 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" ||+ staged.Action != "beacon endpoint repair --user" ||+ !strings.Contains(staged.Message, "/var/folders/xx/T/beacon-launchd-502") {+ 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",+ })+ if unstaged.Status != StatusFail || unstaged.Evidence != "launch_agents_external_volume_unstaged" ||+ !strings.Contains(unstaged.Action, "--no-start") || !strings.Contains(unstaged.Action, "launchctl bootstrap gui/") {+ t.Fatalf("unstaged external-volume check = %#v", unstaged)+ }+}diff --git a/cli/beacon/internal/endpoint/service/forwarder.go b/cli/beacon/internal/endpoint/service/forwarder.goindex f64ec5c3..dd346d67 100644--- a/cli/beacon/internal/endpoint/service/forwarder.go+++ b/cli/beacon/internal/endpoint/service/forwarder.go@@ -185,8 +185,7 @@ func (m ForwarderManager) Unload() error {if runtime.GOOS != "darwin" {return nil}- domain := serviceDomain(m.UserMode)- return runLaunchctlWithContext(domain, ForwarderLabel, "", "bootout", domain+"/"+ForwarderLabel)+ return bootoutLaunchdJob(serviceDomain(m.UserMode), ForwarderLabel)default:return nil}diff --git a/cli/beacon/internal/endpoint/service/inventory.go b/cli/beacon/internal/endpoint/service/inventory.goindex 3c1e7960..4a621963 100644--- a/cli/beacon/internal/endpoint/service/inventory.go+++ b/cli/beacon/internal/endpoint/service/inventory.go@@ -227,8 +227,7 @@ func (m InventoryManager) Unload() error {if runtime.GOOS != "darwin" {return nil}- domain := serviceDomain(m.UserMode)- return runLaunchctlWithContext(domain, InventoryLabel, "", "bootout", domain+"/"+InventoryLabel)+ return bootoutLaunchdJob(serviceDomain(m.UserMode), InventoryLabel)default:return nil}diff --git a/cli/beacon/internal/endpoint/service/launchd.go b/cli/beacon/internal/endpoint/service/launchd.goindex 11ce3c1c..1fc26e56 100644--- a/cli/beacon/internal/endpoint/service/launchd.go+++ b/cli/beacon/internal/endpoint/service/launchd.go@@ -116,9 +116,7 @@ func (b launchdBackend) load(userMode bool) error {}func (b launchdBackend) unload(userMode bool) error {- domain := serviceDomain(userMode)- target := domain + "/" + b.label(userMode)- return runLaunchctlWithContext(domain, b.label(userMode), "", "bootout", target)+ return bootoutLaunchdJob(serviceDomain(userMode), b.label(userMode))}func (b launchdBackend) restart(userMode bool) error {@@ -164,7 +162,21 @@ func launchctlNoSuchProcess(text string) bool {return strings.Contains(text, "No such process") || strings.Contains(text, "Could not find service")}+// loadLaunchdJob bootstraps plistPath into domain, reloading a job that is already registered.+//+// A user LaunchAgent whose plist is off the startup volume is bootstrapped from a staged copy+// instead (see launchd_volume.go, #639); a failure then carries a note naming the volume and the+// manual route.func loadLaunchdJob(domain, label, plistPath string) error {+ bootstrapPath, note := launchdBootstrapPath(domain, plistPath)+ err := bootstrapLaunchdJob(domain, label, bootstrapPath)+ if err != nil && note != "" {+ return fmt.Errorf("%w\n%s", err, note)+ }+ return err+}++func bootstrapLaunchdJob(domain, label, plistPath string) error {out, err := runLaunchctlCommand("bootstrap", domain, plistPath)if err == nil {return nil@@ -239,7 +251,7 @@ func launchctlGuidance(output, domain, label string) string {if target == "" {target = "the Beacon launchd job"}- return fmt.Sprintf("Bootstrap failed: 5 usually means launchd could not read or execute the job. Verify the collector binary referenced by the plist exists and is executable, clear stale state with `launchctl bootout %s`, then inspect launchd logs with `log show --predicate 'process == \"launchd\"' --last 5m`.", target)+ return fmt.Sprintf("Bootstrap failed: 5 usually means launchd could not read or execute the job. Verify the collector binary referenced by the plist exists and is executable, clear stale state with `launchctl bootout %s`, then inspect launchd logs with `log show --predicate 'process == \"launchd\"' --last 5m`. launchd also refuses plists on an external volume, such as a home directory under /Volumes; `beacon endpoint doctor` reports that case.", target)}func serviceDomain(userMode bool) string {diff --git a/cli/beacon/internal/endpoint/service/launchd_volume.go b/cli/beacon/internal/endpoint/service/launchd_volume.gonew file mode 100644index 00000000..043061eb--- /dev/null+++ b/cli/beacon/internal/endpoint/service/launchd_volume.go@@ -0,0 +1,221 @@+package service++import (+ "errors"+ "fmt"+ "os"+ "path/filepath"+ "strings"+)++// A user whose home directory lives on an external volume (`/Volumes/<disk>`, with NFSHomeDirectory+// pointing there) gets every Beacon LaunchAgent refused by launchd: `launchctl bootstrap gui/<uid>+// ~/Library/LaunchAgents/<label>.plist` fails with "Bootstrap failed: 5: Input/output error", the+// install rolls back, and the inventory job never loads (#639). The same plist bootstraps cleanly+// once it is copied to the startup volume, and the job then runs normally with its program and+// config still on the external volume -- so the refusal is about where the job definition is read+// from, not about what the job touches. An independent report against another launchd-managed+// tool shows the same failure and the same cure, with `diskutil enableOwnership` making no+// difference.+//+// Beacon therefore keeps writing the canonical plist to ~/Library/LaunchAgents, where an operator+// and launchd's own login scan expect it, and hands launchctl a byte-identical copy staged in a+// private directory on the startup volume whenever the LaunchAgents directory is on a different+// volume. A home on the startup volume is untouched: its plist is bootstrapped in place as before.++// Seams for tests: which volume a path is on, the path that stands for the startup volume, and+// where a staged copy may go. /Users is on the startup volume's Data half on every supported macOS+// (it is a firmlink into /System/Volumes/Data), which is where both TMPDIR and /private/tmp live;+// "/" itself is the sealed system volume and has a different device number, so it cannot be the+// reference.+var (+ launchdVolumeID = volumeID+ launchdBootVolumeRef = "/Users"+ launchdStagingBases = func() []string { return []string{os.TempDir(), "/private/tmp"} }+)++// LaunchAgentVolume describes where a user LaunchAgent's plist sits relative to the startup volume.+type LaunchAgentVolume struct {+ // PlistDir is the LaunchAgents directory that holds the canonical plist.+ PlistDir string `json:"plist_dir"`+ // External is true when PlistDir is on a volume other than the startup volume.+ External bool `json:"external"`+ // 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"`+ // Reason says how External was decided, for diagnostics.+ Reason string `json:"reason,omitempty"`+}++// InspectLaunchAgentVolume reports whether plistPath is off the startup volume and, if so, where+// Beacon will stage the copy it bootstraps.+func InspectLaunchAgentVolume(plistPath string) LaunchAgentVolume {+ dir := filepath.Dir(plistPath)+ vol := LaunchAgentVolume{PlistDir: dir}+ bootID, bootErr := launchdVolumeID(launchdBootVolumeRef)+ dirID, dirErr := launchdVolumeID(dir)+ switch {+ case bootErr == nil && dirErr == nil:+ vol.External = dirID != bootID+ if vol.External {+ vol.Reason = fmt.Sprintf("%s is on a different volume than %s", dir, launchdBootVolumeRef)+ }+ case underVolumes(dir):+ // No device numbers to compare, so the mount point is the evidence: external and+ // secondary internal volumes are mounted under /Volumes.+ vol.External = true+ vol.Reason = dir + " is under /Volumes"+ }+ if !vol.External {+ return vol+ }+ for _, base := range launchdStagingBases() {+ if strings.TrimSpace(base) == "" {+ continue+ }+ if bootErr == nil {+ if id, err := launchdVolumeID(base); err != nil || id != bootID {+ continue+ }+ } else if underVolumes(base) {+ continue+ }+ vol.StagingDir = filepath.Join(base, launchdStagingDirName())+ break+ }+ return vol+}++func underVolumes(path string) bool {+ if resolved, err := filepath.EvalSymlinks(path); err == nil {+ path = resolved+ }+ return strings.HasPrefix(filepath.Clean(path)+"/", "/Volumes/")+}++// launchdStagingDirName carries the uid so the /private/tmp fallback cannot collide between users.+func launchdStagingDirName() string {+ return fmt.Sprintf("beacon-launchd-%d", os.Getuid())+}++// launchdBootstrapPath returns the path launchctl should bootstrap for plistPath in domain, and a+// note to attach to a bootstrap failure. Only user domains are staged: LaunchDaemons live in+// /Library on the startup volume and are root's.+func launchdBootstrapPath(domain, plistPath string) (string, string) {+ if !strings.HasPrefix(domain, "gui/") {+ return plistPath, ""+ }+ vol := InspectLaunchAgentVolume(plistPath)+ if !vol.External {+ return plistPath, ""+ }+ if vol.StagingDir == "" {+ return plistPath, externalVolumeNote(domain, vol, "", errors.New("no private directory on the startup volume was found"))+ }+ staged, err := stageLaunchdPlist(plistPath, vol.StagingDir)+ if err != nil {+ return plistPath, externalVolumeNote(domain, vol, "", err)+ }+ return staged, externalVolumeNote(domain, vol, staged, nil)+}++// externalVolumeNote explains a bootstrap failure for a plist off the startup volume. It is only+// shown when launchctl fails, so it always ends with the manual route from #639.+func externalVolumeNote(domain string, vol LaunchAgentVolume, staged string, stageErr error) string {+ var b strings.Builder+ fmt.Fprintf(&b, "The LaunchAgents directory %s is not on the startup volume (%s); launchd refuses to bootstrap LaunchAgents from a home directory on an external volume.", vol.PlistDir, vol.Reason)+ if stageErr != nil {+ fmt.Fprintf(&b, " A copy could not be staged on the startup volume: %v.", stageErr)+ } 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)+ return b.String()+}++// 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+// else can write, or another account could replace the job definition between the copy and the+// bootstrap and have launchd run its program as this user. The copy is written to a temporary name+// and renamed into place, which replaces rather than follows anything planted at the final name.+func stageLaunchdPlist(plistPath, stagingDir string) (string, error) {+ data, err := os.ReadFile(plistPath)+ if err != nil {+ return "", err+ }+ if err := os.Mkdir(stagingDir, 0o700); err != nil && !os.IsExist(err) {+ return "", err+ }+ if err := checkPrivateStagingDir(stagingDir); err != nil {+ return "", err+ }+ tmp, err := os.CreateTemp(stagingDir, ".stage-*.plist")+ if err != nil {+ return "", err+ }+ tmpPath := tmp.Name()+ defer os.Remove(tmpPath)+ if _, err := tmp.Write(data); err != nil {+ _ = tmp.Close()+ return "", err+ }+ // launchd refuses a job definition that is group- or world-writable.+ if err := tmp.Chmod(0o644); err != nil {+ _ = tmp.Close()+ return "", err+ }+ if err := tmp.Close(); err != nil {+ return "", err+ }+ dest := filepath.Join(stagingDir, filepath.Base(plistPath))+ if err := os.Rename(tmpPath, dest); err != nil {+ return "", err+ }+ return dest, nil+}++// checkPrivateStagingDir refuses anything but a real directory owned by this user with no group or+// other access.+func checkPrivateStagingDir(dir string) error {+ info, err := os.Lstat(dir)+ if err != nil {+ return err+ }+ if info.Mode()&os.ModeSymlink != 0 || !info.IsDir() {+ return fmt.Errorf("%s is not a directory", dir)+ }+ if uid, ok := fileOwner(info); ok && uid != os.Getuid() {+ return fmt.Errorf("%s is owned by uid %d, not this user", dir, uid)+ }+ if perm := info.Mode().Perm(); perm&0o077 != 0 {+ return fmt.Errorf("%s is mode %o; it must not be accessible to other users", dir, perm)+ }+ return nil+}++// removeStagedLaunchdPlist deletes any staged copy of label's plist. launchd holds a job's+// definition in memory once it is bootstrapped, so the copy only matters for the next bootstrap,+// which restages it; removing it on bootout keeps an uninstall from leaving it behind.+func removeStagedLaunchdPlist(label string) {+ for _, base := range launchdStagingBases() {+ if strings.TrimSpace(base) == "" {+ continue+ }+ dir := filepath.Join(base, launchdStagingDirName())+ if checkPrivateStagingDir(dir) != nil {+ continue+ }+ _ = os.Remove(filepath.Join(dir, label+".plist"))+ }+}++// bootoutLaunchdJob stops and deregisters a job by label, tolerating one that is not loaded, and+// removes a user job's staged plist.+func bootoutLaunchdJob(domain, label string) error {+ err := runLaunchctlWithContext(domain, label, "", "bootout", domain+"/"+label)+ if strings.HasPrefix(domain, "gui/") {+ removeStagedLaunchdPlist(label)+ }+ return err+}diff --git a/cli/beacon/internal/endpoint/service/launchd_volume_test.go b/cli/beacon/internal/endpoint/service/launchd_volume_test.gonew file mode 100644index 00000000..b675e5de--- /dev/null+++ b/cli/beacon/internal/endpoint/service/launchd_volume_test.go@@ -0,0 +1,404 @@+package service++import (+ "errors"+ "fmt"+ "os"+ "path/filepath"+ "runtime"+ "strings"+ "testing"++ "github.com/asymptote-labs/agent-beacon/cli/beacon/internal/testenv"+)++// volumeFixture lays out a fake startup volume and a fake external volume under one temp dir and+// points the volume seams at them, so the detection and staging logic runs on any host. Paths under+// external report device 2; everything else reports device 1, the startup volume.+type volumeFixture struct {+ boot string // stands in for the startup (Data) volume+ external string // stands in for /Volumes/<ExternalDisk>+ staging string // the private staging directory Beacon should create on the startup volume+}++func newVolumeFixture(t *testing.T) volumeFixture {+ t.Helper()+ root := t.TempDir()+ f := volumeFixture{+ boot: filepath.Join(root, "boot"),+ external: filepath.Join(root, "Volumes", "MacintoshExternalNVME"),+ }+ for _, dir := range []string{+ filepath.Join(f.boot, "Users", "test", "Library", "LaunchAgents"),+ filepath.Join(f.boot, "tmp"),+ filepath.Join(f.external, "Library", "LaunchAgents"),+ } {+ if err := os.MkdirAll(dir, 0o755); err != nil {+ t.Fatal(err)+ }+ }+ f.staging = filepath.Join(f.boot, "tmp", launchdStagingDirName())++ oldID, oldRef, oldBases := launchdVolumeID, launchdBootVolumeRef, launchdStagingBases+ launchdBootVolumeRef = filepath.Join(f.boot, "Users")+ launchdStagingBases = func() []string { return []string{filepath.Join(f.boot, "tmp")} }+ launchdVolumeID = func(path string) (uint64, error) {+ if _, err := os.Stat(path); err != nil {+ return 0, err+ }+ if strings.HasPrefix(path, f.external) {+ return 2, nil+ }+ return 1, nil+ }+ t.Cleanup(func() { launchdVolumeID, launchdBootVolumeRef, launchdStagingBases = oldID, oldRef, oldBases })+ return f+}++// externalPlist writes a plist into the external volume's LaunchAgents, the layout from #639.+func (f volumeFixture) externalPlist(t *testing.T, label string) string {+ t.Helper()+ path := filepath.Join(f.external, "Library", "LaunchAgents", label+".plist")+ if err := os.WriteFile(path, []byte(plist(label, "/opt/homebrew/bin/beacon-otelcol", "/x/otelcol.yaml")), 0o644); err != nil {+ t.Fatal(err)+ }+ return path+}++func (f volumeFixture) bootPlist(t *testing.T, label string) string {+ t.Helper()+ path := filepath.Join(f.boot, "Users", "test", "Library", "LaunchAgents", label+".plist")+ if err := os.WriteFile(path, []byte(plist(label, "/opt/homebrew/bin/beacon-otelcol", "/x/otelcol.yaml")), 0o644); err != nil {+ t.Fatal(err)+ }+ return path+}++// recordLaunchctl fakes launchctl with just enough state for the load paths: a bootstrap registers+// the plist's label (unless bootstrapOut makes it fail), a bootout drops it, and print reports+// whether the label is registered, with a pid so the forwarder's start wait is satisfied.+func recordLaunchctl(t *testing.T, bootstrapOut string) *[]string {+ t.Helper()+ calls := &[]string{}+ loaded := map[string]bool{}+ old := runLaunchctlCommand+ runLaunchctlCommand = func(args ...string) (string, error) {+ *calls = append(*calls, strings.Join(args, " "))+ switch args[0] {+ case "bootstrap":+ if bootstrapOut != "" {+ return bootstrapOut, errors.New("exit status 5")+ }+ loaded[strings.TrimSuffix(filepath.Base(args[len(args)-1]), ".plist")] = true+ return "", nil+ case "bootout":+ delete(loaded, filepath.Base(args[len(args)-1]))+ return "", nil+ case "print":+ if loaded[filepath.Base(args[len(args)-1])] {+ return "state = running\npid = 42\n", nil+ }+ return "Could not find service", errors.New("exit status 113")+ }+ return "", fmt.Errorf("unexpected launchctl call: %s", strings.Join(args, " "))+ }+ t.Cleanup(func() { runLaunchctlCommand = old })+ return calls+}++func bootstrapPaths(calls []string) []string {+ var out []string+ for _, c := range calls {+ if fields := strings.Fields(c); len(fields) == 3 && fields[0] == "bootstrap" {+ out = append(out, fields[2])+ }+ }+ return out+}++func TestInspectLaunchAgentVolumeFlagsPlistOffTheStartupVolume(t *testing.T) {+ f := newVolumeFixture(t)+ vol := InspectLaunchAgentVolume(f.externalPlist(t, UserLabel))+ if !vol.External {+ t.Fatalf("plist on the external volume was not flagged: %#v", vol)+ }+ if vol.StagingDir != f.staging {+ t.Fatalf("staging dir = %q, want %q on the startup volume", vol.StagingDir, f.staging)+ }+ if !strings.Contains(vol.Reason, "different volume") {+ t.Fatalf("reason should say why: %q", vol.Reason)+ }+}++func TestInspectLaunchAgentVolumeLeavesStartupVolumeHomesAlone(t *testing.T) {+ f := newVolumeFixture(t)+ vol := InspectLaunchAgentVolume(f.bootPlist(t, UserLabel))+ if vol.External || vol.StagingDir != "" {+ t.Fatalf("a home on the startup volume must not be staged: %#v", vol)+ }+}++// When the volume lookup cannot run (a LaunchAgents directory that does not exist yet, or a stat the+// sandbox refuses), the path is the evidence left: external disks mount under /Volumes.+func TestInspectLaunchAgentVolumeFallsBackToTheVolumesPrefix(t *testing.T) {+ oldID := launchdVolumeID+ launchdVolumeID = func(string) (uint64, error) { return 0, errors.New("stat refused") }+ t.Cleanup(func() { launchdVolumeID = oldID })++ if vol := InspectLaunchAgentVolume("/Volumes/Ext/Library/LaunchAgents/" + UserLabel + ".plist"); !vol.External {+ t.Fatalf("/Volumes path not flagged without a volume lookup: %#v", vol)+ }+ if vol := InspectLaunchAgentVolume("/Users/test/Library/LaunchAgents/" + UserLabel + ".plist"); vol.External {+ t.Fatalf("/Users path flagged without evidence: %#v", vol)+ }+}++// The #639 reproduction: HOME on /Volumes/<disk>, launchd refuses the plist in place. Beacon must hand+// launchctl a byte-identical copy on the startup volume and never the external path.+func TestLoadLaunchdJobBootstrapsAStagedCopyForAnExternalHome(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ f := newVolumeFixture(t)+ calls := recordLaunchctl(t, "")+ source := f.externalPlist(t, UserLabel)++ if err := loadLaunchdJob("gui/502", UserLabel, source); err != nil {+ t.Fatalf("loadLaunchdJob: %v", err)+ }+ staged := filepath.Join(f.staging, UserLabel+".plist")+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != staged {+ t.Fatalf("bootstrap paths = %#v, want only the staged copy %s", got, staged)+ }+ for _, c := range *calls {+ if strings.Contains(c, f.external) {+ t.Fatalf("launchctl was handed the external path: %q", c)+ }+ }+ want, _ := os.ReadFile(source)+ got, err := os.ReadFile(staged)+ if err != nil || string(got) != string(want) {+ t.Fatalf("staged copy differs from the installed plist (err %v)", err)+ }+ if info, _ := os.Stat(f.staging); info == nil || info.Mode().Perm() != 0o700 {+ t.Fatalf("staging dir must be private (0700): %v", info)+ }+ // launchd refuses a job definition that is group- or world-writable.+ if info, _ := os.Stat(staged); info == nil || info.Mode().Perm() != 0o644 {+ t.Fatalf("staged plist mode = %v, want 0644", info)+ }+}++func TestLoadLaunchdJobBootstrapsInPlaceOnTheStartupVolume(t *testing.T) {+ f := newVolumeFixture(t)+ calls := recordLaunchctl(t, "")+ source := f.bootPlist(t, UserLabel)++ if err := loadLaunchdJob("gui/502", UserLabel, source); err != nil {+ t.Fatalf("loadLaunchdJob: %v", err)+ }+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != source {+ t.Fatalf("bootstrap paths = %#v, want the plist in place", got)+ }+ if _, err := os.Stat(f.staging); !os.IsNotExist(err) {+ t.Fatalf("a startup-volume home must not create a staging dir (stat err %v)", err)+ }+}++// LaunchDaemons live in /Library on the startup volume and are root's; staging is a user-domain+// remedy only.+func TestLoadLaunchdJobNeverStagesTheSystemDomain(t *testing.T) {+ f := newVolumeFixture(t)+ calls := recordLaunchctl(t, "")+ source := f.externalPlist(t, SystemLabel)++ if err := loadLaunchdJob("system", SystemLabel, source); err != nil {+ t.Fatalf("loadLaunchdJob: %v", err)+ }+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != source {+ t.Fatalf("bootstrap paths = %#v, want the plist in place for the system domain", got)+ }+}++// If launchd still refuses, the error names the external volume, the copy it tried, and the manual+// route, instead of the generic "verify the collector binary" advice alone.+func TestLoadLaunchdJobExplainsAnExternalHomeWhenBootstrapStillFails(t *testing.T) {+ f := newVolumeFixture(t)+ recordLaunchctl(t, "Bootstrap failed: 5: Input/output error")+ source := f.externalPlist(t, UserLabel)++ err := loadLaunchdJob("gui/502", UserLabel, source)+ if err == nil {+ t.Fatal("loadLaunchdJob succeeded, want the bootstrap failure")+ }+ for _, want := range []string{+ "Bootstrap failed: 5",+ f.external,+ "not on the startup volume",+ filepath.Join(f.staging, UserLabel+".plist"),+ "--no-start",+ "launchctl bootstrap gui/502",+ } {+ if !strings.Contains(err.Error(), want) {+ t.Fatalf("error missing %q:\n%v", want, err)+ }+ }+}++// The staging directory is a fixed name in a temp directory, so it must be one this user created+// and nobody else can write: a planted symlink or a writable directory would let another account+// swap the job definition between the copy and the bootstrap.+func TestLoadLaunchdJobRefusesAnUnsafeStagingDirectory(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ for _, tc := range []struct {+ name string+ plant func(t *testing.T, staging, elsewhere string)+ }{+ {"symlink", func(t *testing.T, staging, elsewhere string) {+ if err := os.Symlink(elsewhere, staging); err != nil {+ t.Fatal(err)+ }+ }},+ {"group writable", func(t *testing.T, staging, _ string) {+ if err := os.Mkdir(staging, 0o700); err != nil {+ t.Fatal(err)+ }+ if err := os.Chmod(staging, 0o770); err != nil {+ t.Fatal(err)+ }+ }},+ } {+ t.Run(tc.name, func(t *testing.T) {+ f := newVolumeFixture(t)+ elsewhere := t.TempDir()+ tc.plant(t, f.staging, elsewhere)+ calls := recordLaunchctl(t, "Bootstrap failed: 5: Input/output error")+ source := f.externalPlist(t, UserLabel)++ err := loadLaunchdJob("gui/502", UserLabel, source)+ if err == nil || !strings.Contains(err.Error(), "could not be staged") {+ t.Fatalf("error = %v, want it to say the copy could not be staged", err)+ }+ if got := bootstrapPaths(*calls); len(got) != 1 || got[0] != source {+ t.Fatalf("bootstrap paths = %#v, want the original plist when staging is refused", got)+ }+ if entries, _ := os.ReadDir(elsewhere); len(entries) != 0 {+ t.Fatalf("staging wrote through the planted directory: %v", entries)+ }+ })+ }+}++// A planted symlink at the staged file's own name is replaced, not followed.+func TestStageLaunchdPlistReplacesAPlantedSymlink(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ f := newVolumeFixture(t)+ source := f.externalPlist(t, UserLabel)+ if err := os.Mkdir(f.staging, 0o700); err != nil {+ t.Fatal(err)+ }+ victim := filepath.Join(t.TempDir(), "victim")+ if err := os.WriteFile(victim, []byte("untouched"), 0o600); err != nil {+ t.Fatal(err)+ }+ dest := filepath.Join(f.staging, UserLabel+".plist")+ if err := os.Symlink(victim, dest); err != nil {+ t.Fatal(err)+ }++ staged, err := stageLaunchdPlist(source, f.staging)+ if err != nil || staged != dest {+ t.Fatalf("stageLaunchdPlist = %q, %v", staged, err)+ }+ if got, _ := os.ReadFile(victim); string(got) != "untouched" {+ t.Fatalf("staging followed the symlink and overwrote %s", victim)+ }+ if info, err := os.Lstat(dest); err != nil || info.Mode()&os.ModeSymlink != 0 {+ t.Fatalf("staged plist should be a regular file: %v %v", info, err)+ }+}++func TestBootoutLaunchdJobRemovesTheStagedCopy(t *testing.T) {+ testenv.RequirePOSIXFileModes(t)+ f := newVolumeFixture(t)+ calls := recordLaunchctl(t, "")+ if err := loadLaunchdJob("gui/502", InventoryLabel, f.externalPlist(t, InventoryLabel)); err != nil {+ t.Fatal(err)+ }+ staged := filepath.Join(f.staging, InventoryLabel+".plist")+ if _, err := os.Stat(staged); err != nil {+ t.Fatalf("staged copy missing after load: %v", err)+ }++ if err := bootoutLaunchdJob("gui/502", InventoryLabel); err != nil {+ t.Fatalf("bootoutLaunchdJob: %v", err)+ }+ if last := (*calls)[len(*calls)-1]; last != "bootout gui/502/"+InventoryLabel {+ t.Fatalf("last launchctl call = %q, want bootout by label", last)+ }+ if _, err := os.Stat(staged); !os.IsNotExist(err) {+ t.Fatalf("staged copy survived bootout (stat err %v)", err)+ }+}++func TestVolumeIDAgreesWithinOneFilesystem(t *testing.T) {+ if runtime.GOOS == "windows" {+ t.Skip("launchd volume detection is not built for Windows")+ }+ dir := t.TempDir()+ sub := filepath.Join(dir, "sub")+ if err := os.Mkdir(sub, 0o755); err != nil {+ t.Fatal(err)+ }+ a, errA := volumeID(dir)+ b, errB := volumeID(sub)+ if errA != nil || errB != nil || a != b {+ t.Fatalf("volumeID(%s)=%d,%v volumeID(%s)=%d,%v; want equal", dir, a, errA, sub, b, errB)+ }+ if _, err := volumeID(filepath.Join(dir, "missing")); err == nil {+ t.Fatal("volumeID of a missing path should fail")+ }+}++// End to end through each user LaunchAgent the endpoint installs: collector, forwarder and the+// inventory job all reached launchd from the external volume in #639. The managers refuse to run+// off macOS, so this half runs on the macOS CI job; the shared path is covered above everywhere.+func TestUserLaunchAgentsBootstrapFromAStagedCopyOnAnExternalHome(t *testing.T) {+ if runtime.GOOS != "darwin" {+ t.Skip("the launchd managers only run on macOS; loadLaunchdJob covers the shared path elsewhere")+ }+ shrinkLaunchdWaits(t)+ f := newVolumeFixture(t)+ testenv.SetHome(t, f.external)+ calls := recordLaunchctl(t, "")++ collector := Manager{UserMode: true, Kind: KindLaunchd}+ if _, err := collector.WriteUnit("/opt/homebrew/bin/beacon-otelcol", "/x/otelcol.yaml"); err != nil {+ t.Fatal(err)+ }+ if err := collector.Load(); err != nil {+ t.Fatalf("collector Load: %v", err)+ }+ forwarder := ForwarderManager{UserMode: true, Kind: KindLaunchd}+ if _, err := forwarder.WriteUnit("/opt/beacon/bin/vector", "/x/vector.toml"); err != nil {+ t.Fatal(err)+ }+ if err := forwarder.Load(); err != nil {+ t.Fatalf("forwarder Load: %v", err)+ }+ inventory := InventoryManager{UserMode: true, Kind: KindLaunchd}+ if _, err := inventory.WriteUnit("/opt/homebrew/bin/beacon", ""); err != nil {+ t.Fatal(err)+ }+ if err := inventory.Load(); err != nil {+ t.Fatalf("inventory Load: %v", err)+ }+ for _, p := range bootstrapPaths(*calls) {+ if !strings.HasPrefix(p, f.staging+string(filepath.Separator)) {+ t.Fatalf("bootstrap from %s, want a staged copy under %s", p, f.staging)+ }+ }+ for _, label := range []string{UserLabel, ForwarderLabel, InventoryLabel} {+ if _, err := os.Stat(filepath.Join(f.staging, label+".plist")); err != nil {+ t.Fatalf("no staged copy for %s: %v", label, err)+ }+ }+}diff --git a/cli/beacon/internal/endpoint/service/service_test.go b/cli/beacon/internal/endpoint/service/service_test.goindex 392f7572..ed819667 100644--- a/cli/beacon/internal/endpoint/service/service_test.go+++ b/cli/beacon/internal/endpoint/service/service_test.go@@ -356,6 +356,10 @@ func TestLaunchctlGuidance(t *testing.T) {if !strings.Contains(withTarget, "launchctl bootout gui/501/"+UserLabel) {t.Fatalf("guidance missing domain/label target: %q", withTarget)}+ // #639: an external-volume home is a known cause of error 5, and doctor names it.+ if !strings.Contains(withTarget, "/Volumes") || !strings.Contains(withTarget, "beacon endpoint doctor") {+ t.Fatalf("guidance should mention the external-volume cause: %q", withTarget)+ }fallback := launchctlGuidance("Input/output error", "", "")if !strings.Contains(fallback, "the Beacon launchd job") {diff --git a/cli/beacon/internal/endpoint/service/volume_unix.go b/cli/beacon/internal/endpoint/service/volume_unix.gonew file mode 100644index 00000000..9f1534b5--- /dev/null+++ b/cli/beacon/internal/endpoint/service/volume_unix.go@@ -0,0 +1,27 @@+//go:build !windows++package service++import (+ "os"+ "syscall"+)++// volumeID returns the device number of the filesystem holding path, following symlinks.+func volumeID(path string) (uint64, error) {+ var st syscall.Stat_t+ if err := syscall.Stat(path, &st); err != nil {+ return 0, &os.PathError{Op: "stat", Path: path, Err: err}+ }+ // Dev is int32 on darwin and uint64 on linux; the conversion is a no-op on the latter.+ return uint64(st.Dev), nil+}++// fileOwner returns the uid that owns info's file.+func fileOwner(info os.FileInfo) (int, bool) {+ st, ok := info.Sys().(*syscall.Stat_t)+ if !ok {+ return 0, false+ }+ return int(st.Uid), true+}diff --git a/cli/beacon/internal/endpoint/service/volume_windows.go b/cli/beacon/internal/endpoint/service/volume_windows.gonew file mode 100644index 00000000..7221ddbe--- /dev/null+++ b/cli/beacon/internal/endpoint/service/volume_windows.go@@ -0,0 +1,16 @@+//go:build windows++package service++import (+ "errors"+ "os"+)++// volumeID is only consulted for launchd, which does not exist on Windows.+func volumeID(string) (uint64, error) {+ return 0, errors.New("volume lookup is not implemented on Windows")+}++// fileOwner has no uid to report on Windows.+func fileOwner(os.FileInfo) (int, bool) { return 0, false }diff --git a/docs/cli/endpoint-paths.mdx b/docs/cli/endpoint-paths.mdxindex 443c18d6..1ef006de 100644--- a/docs/cli/endpoint-paths.mdx+++ b/docs/cli/endpoint-paths.mdx@@ -40,6 +40,8 @@ The Beacon forwarder started by `beacon endpoint connect` is a second, residentThe 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).+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).A supervised collector is a plain background process tracked by a pidfile. It works, but nothing restarts it if it exits or when the machine reboots. `beacon endpoint status` says so explicitly rather than reporting the same health as a real service.diff --git a/docs/platforms/macos.mdx b/docs/platforms/macos.mdxindex ad743731..e41f5d4e 100644--- a/docs/platforms/macos.mdx+++ b/docs/platforms/macos.mdx@@ -68,6 +68,24 @@ If the job or its plist is missing or broken, repair it without reinstalling:beacon endpoint doctor --fix```+### Home directory on an external volume++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.++`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:++```bash title="Manual bootstrap from the startup volume"+beacon endpoint install --user --no-start+mkdir -p -m 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+ launchctl bootstrap "gui/$(id -u)" "$TMPDIR/beacon-launchd/$label.plist"+done+```+## What is macOS-specificMost of Beacon behaves identically everywhere: the event schema, the collector, hooks, the dashboard, and threat detection. These are the parts that do not: