Sage Infrastructure Solutions Group IncSage Infrastructure Solutions Group IncLoading…

Sage Infrastructure Solutions Group Inc

Enrol hosts

A managed host runs keyreeved, which enrols the host, owns Keyreeve's sshd settings, decides each login from the rules the server sends it, and records sessions.

What a host needs

  • Linux with OpenSSH server 7.6 or newer
  • Outbound access to the Keyreeve agent service address (port 4388 unless your administrator put it behind a TCP passthrough on another port), over mutual TLS — agents never accept inbound connections
  • cgroup v2 for session containment (systemd distributions from roughly 2021 onwards)
  • auditd for program logging (optional)

Tested on Debian 12 and 13 and Rocky 9.

Enrol

Create an enrollment token under Admin → Hosts, then run the one-line install command the page shows you on the host. It fetches the agent from the server's agent service and enrols it in one step.

To do it by hand with the keyreeve-agent package already installed (the package has already run keyreeved install, which sets up the helper user, directories and systemd unit):

keyreeved enroll \
  --server https://agents.keyreeve.example.com:4388 \
  --token kret_… \
  --ca-pin sha256:…
systemctl enable --now keyreeved
  • --ca-pin is the fingerprint of the CA that signed the agent service's certificate, shown with the token. It is what stops an agent enrolling against an impostor when the server uses a Keyreeve-generated certificate.

An enrollment token can carry name patterns the host's names must match, host groups and tags every host gets, automatic approval, a use count and an expiry.

Approval

[!NOTE] Unless its token approves hosts automatically, a newly enrolled host waits for an administrator to approve its names. Until then it gets no host certificate, no access rules, no break-glass and no gateway or web terminal sessions.

That is on purpose: anyone holding a token could otherwise claim another host's name and have certificates issued for it. No two hosts may share a name. Approve hosts under Admin → Hosts.

What the agent changes on the host

Keyreeve's sshd settings live only in its own files (sshd_config.d/10-keyreeve.conf, sshd_config.d/06-keyreeve-fips.conf and /etc/ssh/keyreeve-match.conf), never in your sshd_config. A setting — fleet default, overridable per host group or host — chooses whether the agent writes them or an external configuration tool does. Either way the agent checks the effective sshd configuration and reports drift.

Removing the package runs keyreeved uninstall, which takes those settings back out, so uninstalling never strands sshd on a helper that is no longer there.

Updates

Agents update themselves over the signed agent service connection. The new binary has to prove itself — a configuration applied and a heartbeat delivered — or a watchdog rolls it back after five minutes. An update waits while sessions are being relayed through the host (the web terminal, the desktop app, the gateway), for up to 24 hours, so nobody's session is cut off. The fleet default is under Admin → Fleet settings; host groups (Admin → Host groups) and hosts (Admin → Hosts) can override it.