Skip to content

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

12.4 KB
Raw Blame
package service

import (
	"fmt"
	"os"
	"os/exec"
	"path/filepath"
	"runtime"
	"strings"
)

// systemdBackend manages the collector via systemd.
//
// Mapping from the launchd behavior it replaces:
//
//	RunAtLoad=true   -> WantedBy=multi-user.target plus `systemctl enable --now`
//	KeepAlive=true   -> Restart=always with a small RestartSec
//	StandardOutPath  -> the journal, so no /tmp files to manage or rotate
//	gui/<uid> domain -> `systemctl --user`, which additionally needs linger enabled to
//	                    survive logout (see EnableLinger)
type systemdBackend struct{}

var runSystemctlCommand = func(args ...string) (string, error) {
	cmd := exec.Command("systemctl", args...)
	out, err := cmd.CombinedOutput()
	return string(out), err
}

var runLoginctlCommand = func(args ...string) (string, error) {
	cmd := exec.Command("loginctl", args...)
	out, err := cmd.CombinedOutput()
	return string(out), err
}

// lingerSystemdPresent gates the linger helpers on systemd being PID 1.
//
// Separate from the systemdIsInit call in backend detection so linger tests can drive every
// branch on any host. Stubbing detection itself would change which backend Manager picks, which
// is a different question with its own tests.
var lingerSystemdPresent = systemdIsInit

// systemdIsInit reports whether systemd is PID 1.
//
// Checked by reading /proc/1/comm rather than by probing for the systemctl binary: many
// container images ship systemctl while running some other init, and in that case every
// systemctl call fails with "System has not been booted with systemd as init system". Getting
// this wrong would make install appear to succeed and then never start anything.
func systemdIsInit() bool {
	if runtime.GOOS != "linux" {
		return false
	}
	b, err := os.ReadFile("/proc/1/comm")
	if err != nil {
		return false
	}
	return strings.TrimSpace(string(b)) == "systemd"
}

func (systemdBackend) kind() Kind { return KindSystemd }

func (systemdBackend) available() bool { return systemdIsInit() }

func (systemdBackend) unsupportedReason() string {
	if runtime.GOOS != "linux" {
		return "systemd service management is available only on Linux"
	}
	return "systemd is not PID 1 on this host; use --service=none for a supervised collector process"
}

func (systemdBackend) label(userMode bool) string {
	if userMode {
		return SystemdUserUnit
	}
	return SystemdSystemUnit
}

func (b systemdBackend) unitPath(userMode bool) (string, error) {
	if userMode {
		home, err := os.UserHomeDir()
		if err != nil {
			return "", err
		}
		return filepath.Join(home, ".config", "systemd", "user", SystemdUserUnit), nil
	}
	return filepath.Join("/etc/systemd/system", SystemdSystemUnit), nil
}

// systemctlArgs prefixes --user for user-mode units so one code path serves both scopes.
func systemctlArgs(userMode bool, args ...string) []string {
	if userMode {
		return append([]string{"--user"}, args...)
	}
	return args
}

func (b systemdBackend) writeUnit(userMode bool, program, configPath string) (string, error) {
	path, err := b.unitPath(userMode)
	if err != nil {
		return "", err
	}
	if err := ensureDir(path); err != nil {
		return "", err
	}
	if err := os.WriteFile(path, []byte(unitFile(program, configPath, userMode)), 0o644); err != nil {
		return "", err
	}
	// systemd caches unit files; without a reload it will keep using the previous contents,
	// which makes a repair look successful while changing nothing.
	if out, err := runSystemctlCommand(systemctlArgs(userMode, "daemon-reload")...); err != nil {
		return path, systemctlError(out, err, "daemon-reload")
	}
	return path, nil
}

func (b systemdBackend) load(userMode bool) error {
	unit := b.label(userMode)
	if out, err := runSystemctlCommand(systemctlArgs(userMode, "enable", "--now", unit)...); err != nil {
		return systemctlError(out, err, "enable --now "+unit)
	}
	return nil
}

func (b systemdBackend) unload(userMode bool) error {
	unit := b.label(userMode)
	// Stop before disable so a running collector is actually terminated, and tolerate an
	// absent unit: uninstall and repair both call this speculatively.
	if out, err := runSystemctlCommand(systemctlArgs(userMode, "stop", unit)...); err != nil {
		if !systemdUnitMissing(out) {
			return systemctlError(out, err, "stop "+unit)
		}
	}
	if out, err := runSystemctlCommand(systemctlArgs(userMode, "disable", unit)...); err != nil {
		if !systemdUnitMissing(out) {
			return systemctlError(out, err, "disable "+unit)
		}
	}
	return nil
}

func (b systemdBackend) restart(userMode bool) error {
	unit := b.label(userMode)
	out, err := runSystemctlCommand(systemctlArgs(userMode, "restart", unit)...)
	if err == nil {
		return nil
	}
	// A unit that was never enabled cannot be restarted; installing it is the right recovery
	// and mirrors the launchd backend's kickstart-then-load fallback.
	if systemdUnitMissing(out) {
		return b.load(userMode)
	}
	return systemctlError(out, err, "restart "+unit)
}

func (b systemdBackend) status(userMode bool) Status {
	unit := b.label(userMode)
	status := Status{Label: unit}

	// is-enabled exits non-zero for a disabled unit, which is a state rather than a failure,
	// so the output is what matters and the error is ignored.
	enabledOut, _ := runSystemctlCommand(systemctlArgs(userMode, "is-enabled", unit)...)
	enabled := strings.TrimSpace(enabledOut)
	switch enabled {
	case "enabled", "enabled-runtime", "static", "indirect", "linked", "linked-runtime":
		status.Loaded = true
	}

	activeOut, _ := runSystemctlCommand(systemctlArgs(userMode, "is-active", unit)...)
	active := strings.TrimSpace(activeOut)
	status.Running = active == "active"
	if status.Running {
		// A running unit is loaded regardless of whether it is enabled at boot.
		status.Loaded = true
	}

	if !status.Loaded && !status.Running {
		status.Message = strings.TrimSpace(enabled + " " + active)
		if status.Message == "" {
			status.Message = "unit not installed"
		}
	}
	return status
}

// systemdUnitMissing recognizes the several ways systemd reports an absent unit.
func systemdUnitMissing(out string) bool {
	l := strings.ToLower(out)
	return strings.Contains(l, "not loaded") ||
		strings.Contains(l, "could not be found") ||
		strings.Contains(l, "no such file or directory") ||
		strings.Contains(l, "does not exist")
}

func systemctlError(out string, err error, what string) error {
	text := strings.TrimSpace(out)
	guidance := ""
	if strings.Contains(strings.ToLower(text), "interactive authentication required") {
		guidance = "\nsystemd requires privileges for system units; rerun with sudo, or use --user for a per-user service."
	}
	if text == "" {
		return fmt.Errorf("systemctl %s failed: %w%s", what, err, guidance)
	}
	return fmt.Errorf("systemctl %s failed: %s: %w%s", what, text, err, guidance)
}

// EnableLinger allows a --user unit to keep running after the user logs out.
//
// This is the piece with no macOS counterpart: launchd's gui/<uid> domain persists for the
// login session, whereas a systemd user manager is torn down at logout unless linger is set.
// Without it a user-mode install silently stops collecting the moment the user logs out.
// Best-effort, since it needs privileges that a plain user may not have.
//
// The reported outcome is whether linger is actually set afterwards, read back from logind,
// rather than whether the loginctl call exited zero. Those differ in both directions:
// authentication can be declined after a zero exit on some logind versions, and the enable can
// land while a helper process the call spawned fails noisily. Logout persistence is the thing
// the user cares about, so it is the thing that gets checked.
func EnableLinger(username string) (bool, string) {
	if !lingerSystemdPresent() {
		return false, "systemd is not PID 1; linger does not apply"
	}
	if username == "" {
		return false, "no username provided"
	}
	// --no-ask-password keeps loginctl from launching a PolicyKit text agent to prompt for
	// authentication. Linger is an optional, best-effort step during install; a password prompt
	// mid-install is worse than reporting the gap and printing the one command that closes it.
	out, err := runLoginctlCommand("--no-ask-password", "enable-linger", username)
	if LingerEnabled(username) {
		// The success path must say so. It previously returned an empty detail, which the install
		// path reads as "not applicable" -- so the one outcome worth recording, linger actually
		// being enabled, was the one the manifest silently dropped.
		return true, "linger enabled for " + username
	}
	return false, lingerFailureDetail(username, out, err)
}

// lingerFailureDetail explains an unset linger in terms the user can act on.
//
// loginctl can spawn a PolicyKit text agent, and on a host without /usr/bin/pkttyagent that
// prints "Failed to execute /usr/bin/pkttyagent: No such file or directory" -- naming a file the
// user never asked about, in the middle of an otherwise successful install, and not the actual
// reason linger is off. That chatter is dropped. Everything else loginctl says is kept, because
// "Interactive authentication required" and a genuinely broken logind are worth reading.
func lingerFailureDetail(username, out string, err error) string {
	detail := "linger is disabled for " + username
	if reason := withoutAuthAgentChatter(out); reason != "" {
		return detail + ": " + reason
	}
	if err != nil {
		return detail + "; enabling it needs administrator approval"
	}
	// Zero exit, nothing printed, and linger still unset: logind accepted the call and did not
	// apply it. Saying so beats reporting a success the next logout would disprove.
	return detail + " even though loginctl reported no error"
}

// withoutAuthAgentChatter drops PolicyKit-agent noise and returns what is left, on one line.
func withoutAuthAgentChatter(out string) string {
	var kept []string
	for _, line := range strings.Split(out, "\n") {
		line = strings.TrimSpace(line)
		if line == "" || strings.Contains(line, "pkttyagent") || strings.Contains(line, "polkit-agent") {
			continue
		}
		kept = append(kept, line)
	}
	return strings.Join(kept, "; ")
}

// LingerEnabled reports whether linger is on for a user, so doctor can flag the gap.
func LingerEnabled(username string) bool {
	if !lingerSystemdPresent() || username == "" {
		return false
	}
	out, err := runLoginctlCommand("show-user", username, "--property=Linger", "--value")
	if err != nil {
		return false
	}
	return strings.EqualFold(strings.TrimSpace(out), "yes")
}

// systemdArg renders one value as a single ExecStart argument.
//
// systemd splits ExecStart on whitespace, so an unquoted path containing a space becomes two
// arguments and the unit fails with a confusing "No such file or directory". That is not exotic:
// a user-mode install lives under the user's home directory, and `--collector` takes an arbitrary
// path from the caller.
//
// Double quotes are systemd's own quoting, inside which backslash escapes apply -- so both the
// quote and the backslash have to be escaped. `%` is separate: it introduces a unit specifier
// anywhere on the line, quoted or not, and is escaped by doubling.
func systemdArg(value string) string {
	value = strings.ReplaceAll(value, `\`, `\\`)
	value = strings.ReplaceAll(value, `"`, `\"`)
	value = strings.ReplaceAll(value, "%", "%%")
	return `"` + value + `"`
}

// unitFile renders the collector unit.
func unitFile(program, configPath string, userMode bool) string {
	var b strings.Builder
	b.WriteString("[Unit]\n")
	b.WriteString("Description=Beacon endpoint collector\n")
	b.WriteString("Documentation=https://docs.asymptotelabs.ai/cli/endpoint\n")
	// The collector only binds loopback and writes a local log, but ordering after the
	// network target avoids a restart storm during early boot.
	b.WriteString("After=network.target\n")
	b.WriteString("\n[Service]\n")
	b.WriteString("Type=simple\n")
	fmt.Fprintf(&b, "ExecStart=%s --config %s\n", systemdArg(program), systemdArg(configPath))
	// KeepAlive equivalent.
	b.WriteString("Restart=always\n")
	b.WriteString("RestartSec=5\n")
	// stdout/stderr go to the journal, replacing launchd's /tmp/<label>.out files.
	b.WriteString("StandardOutput=journal\n")
	b.WriteString("StandardError=journal\n")
	if !userMode {
		// System mode runs as root because the collector writes /var/log/beacon-agent, which
		// hooks running as the console user also append to. Hardening that is deliberately
		// left for the packaging milestone, where the log directory ownership story is
		// decided.
		b.WriteString("User=root\n")
	}
	b.WriteString("\n[Install]\n")
	if userMode {
		b.WriteString("WantedBy=default.target\n")
	} else {
		b.WriteString("WantedBy=multi-user.target\n")
	}
	return b.String()
}