Upgrading & hardening
The agent runs as root on devices you often cannot physically reach, so its operational story matters as much as its update logic. This page covers how to upgrade it, the constraints it runs under, and what happens when a device leaves the fleet.
Upgrading the agent
Upgrading the agent is the same flow as installing it: stage the new binary and restart the service. Re-running the enrollment installer on a device does exactly this — it picks up the new binary and a freshly enrolled certificate, then restarts the service. The agent's identity, trust anchor, and state directory are unchanged across the upgrade, so an in-place upgrade does not re-enroll the device or disturb its current payloads.
You can confirm the running version with systemctl status meshanics-agent or by
running the binary with -version.
Systemd hardening
The agent ships with a hardened service unit rather than leaving hardening to the operator. The defaults include:
- No new privileges — the agent and anything it execs cannot gain privileges.
- Protected system — the filesystem is read-only except for a short, explicit list of writable paths: the state directory, the configuration directory, and the container runtime trust directories.
- Private temp and protected home — isolated scratch space, no access to user home directories.
- Restart with backoff on failure, but a decommission exit is treated as terminal so a removed device stops cleanly instead of crash-looping.
The agent reads only its own service journal, and only to satisfy an operator-requested log pull.
Least privilege for risky capabilities
The agent never runs a shell. Container runtimes, health-probe binaries, and configuration reloads are all invoked with a fixed argument list. The capabilities that could otherwise be abused — exec health probes, configuration file placement, and reload actions — are disabled until an operator explicitly allowlists exactly which binaries, units, and destinations are permitted. A signed payload can only choose from within those allowlists; it can never extend them. This keeps the blast radius of a compromised or tampered descriptor bounded by device-side policy that the control plane cannot override.
Decommissioning
When the control plane offboards a device, the agent receives a decommission signal and cleans up after itself: it wipes its private key, certificate, CA, trust anchor, and update state, and removes the runtime trust directories it installed. The cleanup is best-effort and never blocks — a partially cleaned device is still fully revoked on the server side, since its certificate is no longer trusted. After cleanup the service exits with a terminal status so the unit stays down rather than restarting against a fleet that no longer recognises it.