Cardinalv0.7.0
Read the docs
DocsLinux hostsCardinal 0.7.0

The agent

What cardinal-agent does on a managed host, and the one thing it is structurally incapable of.

llms.txt

cardinal-agent runs on each managed Linux host. It is a host daemon, not an administrative client, and it holds a credential that proves which machine it is and nothing more.

cardinal-agent enroll -server <url> -token <token>   register this machine's key
cardinal-agent run -server <url>                     serve identity, refresh
cardinal-agent status                                what is cached, how old
cardinal-agent sudoers                               print the drop-in, install nothing
cardinal-agent hostcert                              show the host certificate
cardinal-agent shadow -server <url>                  report what cutting over would change
cardinal-agent doctor                                check prerequisites, change nothing

What run does

  • POSIX identity over systemd's io.systemd.UserDatabase varlink interface, consumed by nss-systemd. No C NSS module, and it is the supported modern replacement for nss_ldap.
  • Sudoers, rendered from the same Cedar policy into /etc/sudoers.d/50-cardinal and validated with visudo -c before it is installed. See sudo.
  • Host certificates, so users verify hosts rather than accepting a fingerprint they will never check. This kills TOFU warnings fleet-wide.
  • Trusted authorities, written to /etc/ssh/cardinal_user_ca.pub with an sshd drop-in naming it, so rotating the SSH CA is not a fleet-wide manual step.
  • An offline cache, so a directory outage is not a host outage.

Local root survives it

The agent is structurally incapable of removing local root access, and that is enforced in code and tested rather than promised. An identity system that can lock the operator out of the machine it is running on has turned a directory outage into a hardware problem.

Where things live

Path What
/etc/cardinal/host_key this host's private key
/var/lib/cardinal/assignment.json the cached assignment
/run/systemd/userdb the socket nss-systemd looks in
/etc/sudoers.d/50-cardinal the rendered drop-in

All four are flags, so a distribution that puts them elsewhere can say so.

Start with doctor

cardinal-agent doctor

It checks the machine's prerequisites and says what is missing, changing nothing. Run it before enroll on any host you are not certain about. It is faster than reading a failure later.