From 326c96dd48582b2bb9913bd3b31a6a46a4cf9958 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 2 Sep 2026 17:02:16 -0700 Subject: [PATCH 1/2] NixOS: declare the agent with services.step-agent; document edge releases Rewrite the NixOS install section around one services.step-agent block: import the module, enable it, and declare team and fingerprint in settings. The rebuild installs the package, starts the agent, and the device enrolls on first start once it has been added via the API, so the interactive register step goes away for fleets. Interactive registration stays as the alternative for empty settings. Add an "Edge releases" subsection: point services.step-agent.package at an overrideAttrs of pkgs.step-agent with the edge tarball URL on packages.smallstep.com and the hex sha256 from the release manifest, which Nix accepts as-is. Name the error a TPM-less host hits, update the uninstall step, and note that on NixOS the unit's gate is ConditionPathExists=. Co-Authored-By: Claude Fable 5.1 --- platform/smallstep-agent.mdx | 85 ++++++++++++++++++++++-------- platform/troubleshooting-agent.mdx | 2 + 2 files changed, 65 insertions(+), 22 deletions(-) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 65a90bd0..57189303 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -288,19 +288,26 @@ curl -fsSL https://packages.smallstep.com/scripts/smallstep-agent-install.sh | s ### NixOS The [`step-agent`](https://search.nixos.org/packages?query=step-agent) package is in nixpkgs, on the `nixos-unstable` channel. -NixOS has no `services.step-agent` module yet, -so the system user, systemd service, and PKCS#11 wiring that the Debian and RPM packages install are declared in your own configuration instead. +The `services.step-agent` module that runs it is not in nixpkgs yet, +so download it from Smallstep and import it into your configuration. +Once the module is in nixpkgs, the `imports` line goes away and your `services.step-agent` block stays as it is.
The agent requires a hardware TPM 2.0 on NixOS. The Debian and RPM packages fall back to a software TPM on hosts without one, but the helper scripts that set that up are not part of the nixpkgs package, -so a host with no /dev/tpmrm0 cannot enroll yet. +so on a host with no /dev/tpmrm0 the service exits with flag --identity-token is required and cannot enroll yet.
-1. If you track a stable NixOS channel, add an overlay so that `pkgs.step-agent` resolves. +1. Download [`step-agent.nix`](https://files.smallstep.com/step-agent.nix), place it alongside your `configuration.nix`, and add `./step-agent.nix` to your `imports` list. + + ```bash + curl -fsSLO https://files.smallstep.com/step-agent.nix + ``` + +2. If you track a stable NixOS channel, add an overlay so that `pkgs.step-agent` resolves. Skip this step on `nixos-unstable`. ```nix @@ -317,29 +324,36 @@ so a host with no /dev/tpmrm0 cannot enroll yet. ]; ``` -2. Download [`step-agent.nix`](https://files.smallstep.com/step-agent.nix), place it alongside your `configuration.nix`, and add `./step-agent.nix` to your `imports` list. - The `.nix` file declares the `step-agent` system user, the systemd service and its restart path unit, the `polkit` rules the agent needs, and the `p11-kit` module that publishes our PKCS#11 server. +3. [Add your devices via API](./enrollment-guide.mdx#add-devices-via-api) so that they are pre-approved, + and look up your team slug and agent CA fingerprint as described in [Pre-registration via API](#pre-registration-via-api). + Then enable the agent: - ```bash - curl -fsSLO https://files.smallstep.com/step-agent.nix + ```nix + services.step-agent = { + enable = true; + settings = { + team = "[team name]"; + fingerprint = "[agent CA fingerprint]"; + }; + }; ``` -3. Rebuild your system: + This declares the `step-agent` system user, the systemd service and its PKCS#11 socket, the `polkit` rules the agent needs, and the `p11-kit` module that publishes the agent's PKCS#11 server. + `settings` is written to `/etc/step-agent/agent.yaml`. + Every host in a fleet gets the same two values; nothing in the file is per-device. + The agent only reads it, and everything it writes lives in `/var/lib/step-agent`. - ```bash - sudo nixos-rebuild switch - ``` + To register interactively instead, leave `settings` out + and run `sudo step-agent register [team name]` after the rebuild. + The agent starts as soon as that writes `agent.yaml`. -4. Register the device with your team: +4. Rebuild your system: ```bash - sudo step-agent register [team name] + sudo nixos-rebuild switch ``` - 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. + This installs the package and enables and starts the agent, which enrolls the device on its first start. 5. Check that it was installed correctly: @@ -350,10 +364,37 @@ so a host with no /dev/tpmrm0 cannot enroll yet. Output: ```bash - step-agent/0.67.3 (linux/amd64) - Release Date: 2026-05-19 15:50 UTC + step-agent/0.69.2 (linux/arm64) + Release Date: 2026-08-31 18:14 UTC ``` - + + And that the service is running: + + ```bash + systemctl status step-agent.service + ``` + +#### Edge releases + +nixpkgs carries a stable release, and only once it has been packaged there. +To run an edge release, or a stable release your channel does not have yet, +point `services.step-agent.package` at the release tarball on `packages.smallstep.com`: + +```nix +services.step-agent.package = pkgs.step-agent.overrideAttrs (final: prev: rec { + version = "0.69.2"; + src = pkgs.fetchurl { + url = "https://packages.smallstep.com/edge/step-agent/linux/${version}/step-agent_${version}_linux_amd64.tar.gz"; + sha256 = "1c8217188733c3a6ea558d399936825b426164d6e01d6f1c0ca4a67944f349fd"; + }; +}); +``` + +Pick the version on [releases.smallstep.com](https://releases.smallstep.com) and copy the `sha256` of the tarball from its listing there, +or from the version's manifest at `https://packages.smallstep.com/edge/step-agent/linux/[version]/index.json`. +Nix accepts the hex form as-is. +On `aarch64` hosts, use the `_linux_arm64.tar.gz` file and its hash. +Then run `sudo nixos-rebuild switch` and confirm with `step-agent version`. ## Registering and approving endpoints @@ -466,7 +507,7 @@ To uninstall the Smallstep Agent from a Linux system: sudo apt-get remove step-agent ``` - **For NixOS:** remove `./step-agent.nix` from your `imports` list, then run `sudo nixos-rebuild switch`. + **For NixOS:** remove the `services.step-agent` block and `./step-agent.nix` from your `imports` list, then run `sudo nixos-rebuild switch`. 2. Optionally, remove configuration and certificate files: diff --git a/platform/troubleshooting-agent.mdx b/platform/troubleshooting-agent.mdx index da9f6202..3d62dede 100644 --- a/platform/troubleshooting-agent.mdx +++ b/platform/troubleshooting-agent.mdx @@ -604,6 +604,8 @@ 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) ``` +On NixOS the check is `ConditionPathExists=`. + This may indicate the device needs to be registered and approved. See [Registering and Approving Endpoints](./smallstep-agent.mdx#registering-and-approving-endpoints). From 3048711116208839db6ec21e3bd45f8db0ba2440 Mon Sep 17 00:00:00 2001 From: Carl Tashian Date: Wed, 2 Sep 2026 17:10:43 -0700 Subject: [PATCH 2/2] NixOS: registering interactively alongside declared settings With settings declared, agent.yaml is a store symlink, so document the --skip-config form of register, which registers the device without attempting to rewrite the declared file. Co-Authored-By: Claude Fable 5.1 --- platform/smallstep-agent.mdx | 3 +++ 1 file changed, 3 insertions(+) diff --git a/platform/smallstep-agent.mdx b/platform/smallstep-agent.mdx index 57189303..1a5dcd96 100644 --- a/platform/smallstep-agent.mdx +++ b/platform/smallstep-agent.mdx @@ -346,6 +346,9 @@ so on a host with no /dev/tpmrm0 the service exits with flag To register interactively instead, leave `settings` out and run `sudo step-agent register [team name]` after the rebuild. The agent starts as soon as that writes `agent.yaml`. + With `settings` declared, you can still register a device interactively: + run `sudo step-agent register [team name] --skip-config`, + which registers the device without trying to rewrite the file you declared. 4. Rebuild your system: