From f8051f80c425f0a6c26e27d65196f9d3c3f7e992 Mon Sep 17 00:00:00 2001 From: Josh Drake Date: Wed, 26 Aug 2026 11:51:00 -0500 Subject: [PATCH] NixOS: agent.yaml can be declared, not registered The NixOS instructions told readers not to manage agent.yaml with environment.etc, on the grounds that it "produces a read-only symlink into the Nix store, and the service refuses to start". The diagnosis was wrong and the advice ruled out the deployment NixOS users actually want. Neither the symlink nor the file mode was the problem. The unit gated on ConditionPathIsReadWrite=, which per systemd.unit(5) tests whether the underlying filesystem is mounted read-only, not whether the file is writable, and it resolves symlinks. NixOS remounts /nix/store read-only at boot, so the check landed there and skipped the unit. The agent itself reads a mode 0444 agent.yaml happily and never writes to it; everything it writes lives in /var/lib/step-agent. agent#1205 changes that gate to ConditionPathExists=, which is the question the unit meant to ask all along. So point readers at the declarative form instead, wired to the pre-registration flow that already documents where the team slug and CA fingerprint come from. Also refresh the troubleshooting callout for the new directive name, and say that older agents report the same check under the old one, so the message matches whichever version a reader has installed. Merge after agent#1205, which is what updates the step-agent.nix published to files.smallstep.com. Refs OFF-19. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_01RkEcowtxSeqvb2pLWC3u5J --- platform/smallstep-agent.mdx | 21 ++++++++++++++++++--- platform/troubleshooting-agent.mdx | 4 +++- 2 files changed, 21 insertions(+), 4 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 65a90bd0..8e37e835 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -337,9 +337,24 @@ so a host with no /dev/tpmrm0 cannot enroll yet. ``` Registration writes `agent.yaml` into `/etc/step-agent`, - which systemd creates and keeps writable through `ConfigurationDirectory=`. - Do not manage `agent.yaml` with `environment.etc`: - that produces a read-only symlink into the Nix store, and the service refuses to start. + which systemd creates through `ConfigurationDirectory=`. + + You can declare `agent.yaml` instead of registering interactively, + which is what makes a hands-off NixOS deployment possible. + Follow [Pre-registration via API](#pre-registration-via-api) to add and approve your devices + and to find your team slug and agent CA fingerprint, then declare the file and skip this step: + + ```nix + environment.etc."step-agent/agent.yaml".text = '' + team: "[team name]" + fingerprint: "[agents CA fingerprint]" + ''; + ``` + + The agent only ever reads this file. + Everything it writes lives in `/var/lib/step-agent`, + so serving `agent.yaml` from the Nix store is fine. + Every host in a fleet gets the same two values; nothing in it is per-device. 5. Check that it was installed correctly: diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index da9f6202..e0b0e2b4 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -602,8 +602,10 @@ as shown in [the NixOS install instructions](./smallstep-agent.mdx#nixos). If the agent won't start, check for this message in the logs: ``` step-agent.service was skipped because of an unmet condition check -(ConditionPathIsReadWrite=/etc/step-agent/agent.yaml) +(ConditionPathExists=/etc/step-agent/agent.yaml) ``` +Older agents report the same check as `ConditionPathIsReadWrite=`. + This may indicate the device needs to be registered and approved. See [Registering and Approving Endpoints](./smallstep-agent.mdx#registering-and-approving-endpoints).