System Services
On servers, run detent-authority and detent-agent under the platform’s service
manager, as a dedicated unprivileged account. The repository ships templates
for systemd, launchd and FreeBSD rc.d in packaging/, installed to
share/detent/ by cmake --install.
Layout
Section titled “Layout”| Platform | Configuration | Agent runtime | Service state | Logs |
|---|---|---|---|---|
| Linux | /etc/detent | /run/detent | /var/lib/detent | systemd journal |
| FreeBSD | /usr/local/etc/detent | /var/run/detent | /var/db/detent | /var/log/detent |
| macOS | /Library/Application Support/Detent | /var/run/detent | /var/db/detent | /var/log/detent |
- Configuration is root-owned and readable by the service account.
- Service state is owned by the service account, mode
0700. - The agent’s runtime directory is service-owned, mode
0755, with a0644pid file, so every local user can check status, and only the service account can change it.
The units pass explicit configuration files, so create them first. Create the authority and agent configurations:
echo '{"authority": "/etc/detent/authority.json"}' | sudo tee /etc/detent/detent-authority.jsonecho '{"managed_path": "/etc/detent/managed.json"}' | sudo tee /etc/detent/agent.jsonThe agent exits with no source configured unless managed_path (or
--managed) names the private managed configuration.
Linux: systemd
Section titled “Linux: systemd”Create the detent system user and group without a login shell, then install
the units:
sudo useradd --system --no-create-home --shell /usr/sbin/nologin detentsudo cp /usr/local/share/detent/systemd/*.service /etc/systemd/system/sudo systemctl daemon-reloadsudo systemctl enable --now detent-authority detent-agentsystemd creates and owns the runtime and state directories through
RuntimeDirectory= and StateDirectory=, and sends stdout and stderr to the
journal:
journalctl -u detent-authority -u detent-agentdetent get search:max_results --systemThe units run as detent, use ProtectSystem=strict, ProtectHome,
PrivateTmp and NoNewPrivileges, and grant no extra capabilities.
Configuration changes take effect on restart.
macOS: launchd
Section titled “macOS: launchd”- Create a
_detentservice account and group without an interactive login. - Create
/var/run/detent(0755),/var/db/detent(0700) and/var/log/detent(0750), owned by_detent. - Install
org.detent.*.plistin/Library/LaunchDaemons/, owned by root with mode0644. Adjust/usr/local/binif you installed elsewhere.
sudo launchctl bootstrap system /Library/LaunchDaemons/org.detent.prepare-runtime.plistsudo launchctl bootstrap system /Library/LaunchDaemons/org.detent.detent-authority.plistsudo launchctl bootstrap system /Library/LaunchDaemons/org.detent.detent-agent.plistThe root-owned org.detent.prepare-runtime job recreates only the runtime
directory after a reboot. launchd doesn’t order jobs, so the agent relies on
KeepAlive to retry if it starts first. launchd captures stdout and stderr in
/var/log/detent; rotate them with the host’s logging policy. Don’t use
--daemonize under launchd.
FreeBSD: rc.d
Section titled “FreeBSD: rc.d”sudo pw useradd detent -d /nonexistent -s /usr/sbin/nologinsudo install -m 0755 /usr/local/share/detent/rc.d/detent-authority /usr/local/etc/rc.d/sudo install -m 0755 /usr/local/share/detent/rc.d/detent_agent /usr/local/etc/rc.d/sudo sysrc detent_authority_enable=YES detent_agent_enable=YESsudo service detent-authority startsudo service detent_agent startThe scripts supervise the daemons with daemon(8), using separate supervisor
pidfiles, run them as detent, and write output to /var/log/detent. Add
/var/log/detent/*.log to newsyslog and send HUP to the supervisor to reopen
output after rotation.
Operating System Agents
Section titled “Operating System Agents”detent get NAME --systemdetent-agent --status --systemWith --system, readers attach to the managed agent and never start a private
replacement in a user’s home. If the service isn’t running, get says so;
--default VALUE still provides a per-call fallback. Stop and restart through
the service manager.
Managed Agents
Section titled “Managed Agents”Managed generations are persistent state, separate from runtime files: the
systemd template provisions StateDirectory=detent-agent (/var/lib/detent-agent,
mode 0755). On macOS and FreeBSD, provision /var/db/detent-agent owned by
the service account. Keep managed.json private (0600) and distribute the
public agent.json separately.
Durable relay
Section titled “Durable relay”The optional durable relay has matching systemd, launchd and rc.d templates. It uses relay.json, private durable roots and authenticated TLS on loopback port 8318 by default. Run it in the foreground under the service manager. Hosting remains under Stage 5B qualification.