- Nix 96.9%
- Shell 3.1%
|
All checks were successful
eval / eval (push) Successful in 1m30s
The everyday admin key that already holds the BB Open fleet's secrets, private half in the password manager. The FIDO2 keys in admins.nix cannot be age recipients. One holder for the fieldlab, a second before the fleet lives longer. |
||
|---|---|---|
| .forgejo/workflows | ||
| certs | ||
| modules | ||
| secrets | ||
| .gitignore | ||
| catalog.json | ||
| flake.lock | ||
| flake.nix | ||
| fleet.json | ||
| hardware-profiles.json | ||
| LICENSE | ||
| README.md | ||
| regen-catalog.sh | ||
| secrets.nix | ||
Fieldlab overlay
The Sextant fleet overlay for the laptops of the Fieldlab Soevereine Basis
(23-25 November 2026). It is the git repository the Sextant console at
https://sextant.fieldlab.bb-open.com writes to and the laptops pull their
configuration from.
A laptop built from this overlay:
- logs people in from the directory of the
ldapFundament plugin, through SSSD over LDAPS (ldaps://ldap.fieldlab.bb-open.com:636, basedc=dawo,dc=lab, people underou=people,dc=dawo,dc=lab, bind accountcn=sssd,ou=service-accounts,dc=dawo,dc=lab, certificate verified against the plugin's CA); - boots with Secure Boot (per-device keys) and unlocks its encrypted disk from the TPM2;
- has no local break-glass administrator and no password for any admin: named admins log in over SSH through the mesh with a hardware key;
- joins the NetBird mesh at
https://netbird.fieldlab.bb-open.comheadlessly with a setup key; - is managed by the Sextant console: the agent checks in, comin pulls this repository from the branch of the device's wave, and the root executor carries out console intents (lock, reboot, diagnostics, the Secure Boot and TPM2 steps of the provisioning wizard).
It has the shape of Sextant's reference overlay (examples/overlay in
DAWO-Sextant v0.93.0): fleet.json
v3 in, one NixOS host per device out, through Sextant's generator. The
dawo.* option surface comes from DAWO-Core
v0.2.1.
Layout
| Path | What it is |
|---|---|
flake.nix |
Inputs (DAWO-Core v0.2.1, Sextant v0.93.0) and the generator call: per device, the baseline + workplace image + hardware profile + resolved settings. |
flake.lock |
The exact revisions. Bump with nix flake update. |
fleet.json |
The fleet as data: org settings (directory login, mesh, KDE Plasma desktop, office and communication apps), groups, devices, waves, secret names. The console edits this file; edit it by hand only when the console is not the way. |
catalog.json |
Generated: the settings the console can show. ./regen-catalog.sh after any module change or core bump. |
hardware-profiles.json |
Operator-facing description of each hardware profile (imaging steps, disk layout) for the console's Hardware and Enrollment pages. |
modules/sextant.nix |
Connects the generator's bridge options to the core: comin follows this repo on the wave's branch, agent and executor on. |
modules/integrations.nix |
Directory login (identity.*) and mesh (netbird.*) as console-configurable settings. |
modules/secrets.nix |
Every secrets/<name>.age becomes /run/agenix/<name> on the device. |
modules/comin-*.nix |
Two comin fixes: a changed branch takes effect without a manual restart, and a comin-applied generation survives a reboot. |
modules/catalog-labels.nix |
Console labels for DAWO-Core v0.2.1 options that Sextant v0.93.0 has no label for; without them the catalog export refuses to run. |
modules/unavailable.nix |
Wazuh and the update maintenance window: named by Sextant's catalog, not implemented here, so any value is refused by the gate. |
modules/admins.nix |
Turns the core's local administrator dawo off; named admins in wheel with FIDO2 SSH keys and no password, port 22 on the NetBird interface only. |
certs/ldap-ca.pem |
The directory's CA. A placeholder until day 1; see below. |
secrets.nix |
agenix recipients (admin keys and device host keys). Empty until day 2. |
secrets/ |
Encrypted secrets. Empty until day 2. |
What the console needs
| Overlay repository | https://forgejo.bb-open.com/bbopen/fieldlab-overlay.git, branch main |
| Write access | The console commits every change and pushes main and the ring branches (rings/pilot, rings/production). Give it a token of a machine account with write access to this repository only, delivered through the Sextant plugin's git credential (a netrc Secret; gitRemote.netrcSecret in the Helm chart). It is never committed here. |
| Read access for devices | None needed: the repository is public, so comin pulls it anonymously and no laptop carries a git credential. |
| Agent check-in | https://sextant.fieldlab.bb-open.com (modules/sextant.nix). The per-device credential is minted by the console at enrolment and written by the imaging station to /var/lib/sextant-agent/credential. It is not an agenix secret and never passes through git. |
| Catalog | catalog.json in this repository. The Integrations page shows Directory login and NetBird as available once it is committed. |
Waves
fleet.json declares the rollout the way Sextant v0.93.0 reads it
(rollout.rings, in promotion order; handbook concepts/rollout.md):
| Wave | Group | Gates |
|---|---|---|
| Pilot | pilot |
soak 15 min, manual approval before promotion, evidence floor 1 device |
| Production | production |
health floor 95%, no soak |
A device follows the branch of the first released wave whose group covers it:
rings/pilot or rings/production, and main when it is in no wave. The
console's rollout engine advances those branches; comin on the device notices
on its next poll. Rollouts start on their own when a commit reaches main
(auto-flow is on by default when rings exist).
fieldlab-01 and fieldlab-02 are example records in the pilot wave, with
the generic Intel profile. The production group is empty and ready.
Day 2 runbook
Steps 8-10 of the fieldlab demo script. ORG is the Fundament organisation
the plugins run in.
Before imaging (end of day 1)
-
Fill in the directory CA. The
ldapplugin generates it on install. From the repository root:kubectl -n plugin-ORG--ldap get cm ldap-ca -o jsonpath='{.data.ca\.crt}' > certs/ldap-ca.pem grep -c 'BEGIN CERTIFICATE' certs/ldap-ca.pem # 1 (or more), not 0 git commit -m "Add the fieldlab directory CA" certs/ldap-ca.pemThe CA is public material. Until it is in, every host evaluates with a warning and SSSD refuses the directory (
ldap_tls_reqcert = demand). -
Admin identity.
secrets.nixnames the operator's everyday admin key (ssh-ed25519, private half in the password manager) as the one person who can re-encrypt the secrets after a laptop is re-imaged. One holder is enough for the fieldlab; name a second before this fleet is used for longer. Re-encrypting needs that key:agenix -r -i <key>. -
Check the admins.
modules/admins.nixnames who may administer the laptops: SSH keys only, no password, reachable through the mesh only. There is no local administrator to fall back on, so the list must hold at least one person whose hardware key is at hand on day 2. The build refuses an empty list. -
Create the NetBird setup key in the NetBird dashboard: reusable, expiring after the fieldlab, usage limit about the number of laptops, auto-assigned to a group for the laptops. Keep it in the password manager until the secrets are encrypted.
-
Add the real people to the directory (
ldapaddascn=admin, see the ldap hand-off). The demo people work for a first test. -
Console. The overlay repository is connected (table above), the catalog shows both integrations, and the Secrets page lists the two names from
fleet.json(ldap-bind-sssd,netbird-setup-key).
Image (step 8)
On the console's Enrollment page (handbook operators/image-devices.md):
pick the station, boot each laptop from the imaging stick, and for the batch
set hardware profile generic-intel-laptop (or generic-amd-laptop), class
laptop, group pilot, and a tag per laptop (fieldlab-01, fieldlab-02,
...). Dispatch. The station installs each laptop with nixos-anywhere and
writes its agent credential; the laptop reboots and checks in.
Image ONE laptop first and prove the admin path before the rest. There is
no local administrator, so a laptop nobody can reach over SSH can only be
fixed through git or by imaging it again. The laptop joins the mesh once
its secrets are encrypted ("Encrypt the secrets" below, with its host key
only; agenix -r adds the others later). Then, from a machine in the mesh:
netbird status --detail | grep -A2 fieldlab-01 # its mesh address
ssh bbuijs@<mesh address> sudo true && echo admin ok # touch the key
Secure Boot and TPM2 (part of imaging)
Both are on for the whole fleet (secureboot.enable and
diskUnlock.tpm2.enable at org scope, DAWO-Core's lanzaboote and TPM2
blocks), as in production. What has to happen per laptop:
- Firmware, once, before booting the imaging stick: enable the TPM2 (Security Chip) and clear it; enable Secure Boot and put it in setup mode (Lenovo F1: "Reset to Setup Mode"; HP F10: clear the Secure Boot keys, on some models first disable "Secure Boot Keys Protection"; Dell F2: "Expert Key Management", delete all keys). The hardware profile's steps say the same on the Enrollment page.
- Install (station, automatic): the station generates per-device
Secure Boot keys, lanzaboote signs the boot chain with them during the
install (
/var/lib/sbctl), and it stages a one-shot LUKS enrol key and the disk recovery phrase (sealed in the console, owner-only reveal). - First boots (executor, automatic): the provisioning wizard sends
sextant-actdthrough the ceremony: with the firmware in setup mode it enrols the keys (sbctl enroll-keys --microsoft) and reboots; with Secure Boot enforcing it seals the LUKS key to the TPM2 on PCR 7 (systemd-cryptenroll), mints the recovery key for escrow, shreds the enrol key and reboots. From then on the disk unlocks without a prompt. The wizard turns green only on what the laptop reports.
A laptop whose firmware is not in setup mode (unknown model, keys
protected, step 1 skipped) still boots: the boot chain is signed, the
firmware just does not enforce it yet. The wizard stays on the Secure Boot
phase with the firmware instruction, TPM2 is not sealed, and the disk asks
for the recovery phrase at every boot (reveal it in the console). Fix: use
the wizard's reboot control, enter the firmware, find the option that clears
the factory keys or resets to setup mode, save, and boot; the executor
continues by itself. If the firmware has no way to reach setup mode, record
it as an exception for that device in the console (device-level
secureboot.enable and diskUnlock.tpm2.enable false, with the reason under
accepted) and add the model's quirk to hardware-profiles.json. Never
image a laptop by hand with Secure Boot on and no keys at /var/lib/sbctl:
the lanzaboote install fails.
The two example records already carry the tags fieldlab-01 and
fieldlab-02. Reuse those tags, or delete the example records from
fleet.json before dispatching if the console refuses an existing tag.
At this point a laptop runs, checks in and pulls updates, but has no secrets: SSSD cannot bind and NetBird does not enroll. That is expected.
Encrypt the secrets (step 9, first half)
Done by a person holding an admin identity, on their own workstation, after the laptops are imaged (a secret can only be encrypted to a host key that exists). Secrets never go through the console.
-
Collect the host keys of the new laptops: from the console's device page (the imaging station reports each host key), or on the imaging network:
ssh-keyscan -t ed25519 <laptop-ip> 2>/dev/null | cut -d' ' -f2-Put each one in
secrets.nixunderdevices, keyed by its tag. -
Encrypt with agenix (
nix run github:ryantm/agenix --), byte-exact (printf, neverecho):# SSSD bind password: one line, LDAP_BIND_PW=<password> kubectl -n plugin-ORG--ldap get secret ldap-bind-sssd -o jsonpath='{.data.LDAP_BIND_PASSWORD}' \ | base64 -d | { printf 'LDAP_BIND_PW='; cat; printf '\n'; } \ | EDITOR='cp /dev/stdin' agenix -e secrets/ldap-bind-sssd.age # NetBird setup key: the key only, no newline read -rs NB_KEY && printf '%s' "$NB_KEY" \ | EDITOR='cp /dev/stdin' agenix -e secrets/netbird-setup-key.age; unset NB_KEYNo value lands on a command line or in shell history.
-
Commit and push
secrets.nixandsecrets/*.agetomain(pull first: the console commits tomaintoo). The push starts a rollout: the pilot wave gets the secrets, NetBird enrolls, SSSD binds.
A laptop added later, or re-imaged: add or replace its host key in
secrets.nix, then agenix -r (re-encrypts every file for the new
recipient set), commit, push.
Enrol and log in (step 9, second half)
On a laptop, once the rollout has reached it:
sssctl domain-status ldap # Online status: Online
getent passwd <uid> # a person from ou=people
netbird status # Management: Connected
Then log in at the login screen as a person from the directory; the home directory is created on first login.
Production (step 10)
- In the console, move laptops from group
pilottoproduction. Keep at least one laptop (fieldlab-01) inpilotas the canary: the pilot wave needs one reachable device as evidence before a rollout can promote. If every laptop moves, remove the pilot wave from the rollout plan as well. - A moved laptop follows
rings/productionfrom its next update; the comin guard restarts comin so the new branch takes effect without a visit. - Change a setting in the console (for example Offline login validity on the Integrations page). It lands on the pilot wave first; approve the gate on the Updates board, and it reaches production. Compliance and status are on the device pages.
Adding a laptop model
The fieldlab models are not known in advance, so the overlay ships the core's generic starters. Once a model is known:
-
Add a module in
hardware/, for examplehardware/lenovo-t14-gen4.nix:{ inputs, ... }: { imports = [ inputs.nixos-hardware.nixosModules.lenovo-thinkpad-t14 ]; }The core's generic hardware baseline already comes with every laptop (through
profiles-dawo-generic); the model module only adds that model's quirks. Prefer a nixos-hardware profile; without one, compose itscommon-*profiles, or let nixos-facter detect the machine at install (DAWO-Coremodules/hardware/hardware.md, "Adding a device"). -
Register it in
flake.nixunderhardwareProfiles(lenovo-t14-gen4 = ./hardware/lenovo-t14-gen4.nix;). -
Describe it in
hardware-profiles.json(vendor,modelssubstrings as the firmware reports them, disk layout, firmware steps), so the console suggests it for matching laptops on the Enrollment page. -
Check that a device on it evaluates (below), commit, push.
The disk layout is the core's disko-single-nvme-luks (/dev/nvme0n1); a
model with another disk needs its own layout.
Checking it locally
Evaluation only; nothing is built.
nix flake show
nix eval .#nixosConfigurations.fieldlab-01.config.system.build.toplevel.drvPath
nix eval .#nixosConfigurations.fieldlab-01.config.services.sssd.settings --json
nix eval .#nixosConfigurations.fieldlab-01.config.services.netbird.clients.dawo.environment --json
./regen-catalog.sh --check
Licence
EUPL-1.2, like Sextant. See LICENSE.