Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 25 additions & 0 deletions docs/architecture/GLOSSARY.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,31 @@ and may change without reopening the ruling. Authority:
`architecture-DEFINITIVE-v3.md` D45, with its open
points in §12.

### nix2cf

**A referent that moved.**

- **Current — the Nix module frontend.** The compiler plugin
`plugins/frontends/nix/` that renders a Nix-authored Site Model to the
same JSON as the YAML frontend (map D12). Not built yet.
- **Before 2026-11-13 — the whole compiler**, and the separate repository
`frdminc/nix2cf` that held it (`nix2cf buildfile`). That compiler was
folded into tendcf under `compiler/` on 2026-11-13 (#45), and the
repository was archived the same day. Older documents and handoffs use
the old sense, and that prose is not rewritten (only their paths change
in the restructure, `plugin-layout.md` §5).
- **Which sense holds when.** Until the restructure
(`plugin-layout.md` §5, step 4) the only thing that ships under the name
is still the old compiler: the package `nix2cf` and its command
`nix2cf buildfile`, first in `frdminc/nix2cf`, now under `compiler/`.
The restructure replaces that command with `tendcf compile`, with no
alias, and renames the package `tendcf`; from then on `nix2cf` means
only the Nix frontend. The "Current" sense above is the decided
meaning, for a plugin not yet built.

Authority: `architecture-DEFINITIVE-v3.md` D46 (amending D12 and D21);
layout and order of the move in `plugin-layout.md`.

### coverage

**One enum, three values**: `comprehensive`, `not-yet-migrated`,
Expand Down
3 changes: 3 additions & 0 deletions docs/architecture/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,9 @@ gates — issue #2) and [`upstream-overlay.md`](upstream-overlay.md) (the
patch overlay on libntech / cfengine/core in [`../../overlay/`](../../overlay/)
— issue #3). [`upstream-register.md`](upstream-register.md) is the living
record of every CFEngine/libntech defect and contribution.
[`plugin-layout.md`](plugin-layout.md) is the repository layout and the
compiler's plugin kinds, decided 2026-11-13 together with moving the
compiler into tendcf (map D46).

Site Model contract (JSON Schema, fixtures, lint):
[`../../schema/`](../../schema/), [`../../examples/`](../../examples/),
Expand Down
93 changes: 71 additions & 22 deletions docs/architecture/architecture-DEFINITIVE-v3.md

Large diffs are not rendered by default.

164 changes: 114 additions & 50 deletions docs/architecture/change-process.md

Large diffs are not rendered by default.

16 changes: 10 additions & 6 deletions docs/architecture/linux-targets.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ is a derivation kept in the host flake, not in this repo.
| 3 | Fail-closed guard in `policy/tendcf_services.cf`: refuse any unit flavour the bundle does not implement, with a negative test. **Done 2026-10-29:** a present entry is actuated only when its `unit` flavour is `launchd` AND the host is `darwin`; otherwise it is refused and reported by name and flavour. `tests/policy/run.sh` checks 4 (systemd entry, every host) and 5 (launchd entries on a non-Darwin host, CI only). Before this, a systemd entry would have been rendered as a `LaunchDaemons` plist and a launchd entry on Linux handed to a `launchctl` that is not there. |
| 4 | One `schema_version` bump from an adapter prototype: richer goal-file systemd flavour (scope, restart, install target, externally-written unit), writer vocabulary with `dpkg`, `nixos` and `nix-darwin`, and an inventory schema carrying `supervisor` and distro family. **Slice A done 2026-10-31:** the family went to `schema_version: 2` (goal-file, goal-diff and approval-record; every fixture and digest regenerated; case 13 now claims 3). `unit.systemd` gained `restart` (`no`/`on-failure`/`always`) and `wanted_by` (a `*.target`), the two knobs the renderer writes, both explicit. A systemd entry's argv and `working_dir` are held to a safe alphabet (no `"` `\` `$` `%` or control character; `working_dir` limited to `[A-Za-z0-9._+@:-]` segments): refused structurally, not escaped, so a value systemd would re-read never reaches the unit file (`service_present` `allOf`; negative cases 70-72). **Slice B, writers, done 2026-10-31 (`schema_version: 3`):** the writer vocabulary gained `nixos` and `dpkg` (`nix-darwin` was already there) in both the goal file and `launchd-writers`; case 13 claims 4; negative case 73 (unknown writer); `deploy/linux/passthrough/goal-file.json` was the first `nixos`-writer goal file, projecting to `{"vars":{}}`. **Schema v4 (2026-11-01, [schema-v4-reconciliation-2026-10-31.md](schema-v4-reconciliation-2026-10-31.md)):** `supervisor` is a required `device-trust` fact (launchd, systemd, runit, nixos); a `nixos` host carries no service, interlock or unit-writer anywhere, and `nixos` left the writer vocabulary; the passthrough fixture says `supervisor: nixos`; cases 93-112. **Schema v5 (2026-11-02, [schema-v5-dpkg-reconciliation-2026-11-02.md](schema-v5-dpkg-reconciliation-2026-11-02.md), slice S2):** Debian package claims: the `unit-package` kind (binary package names, systemd hosts only), `dpkg` left the `unit-writer` writer vocabulary (a package's units are claimed by a `unit-package` entry, never a writer value) and `tendcf-install` joined it (one unit, `tendcf-execd.service`); the `unit-writer` key grammar is exact names, template keys and prefixes (a systemd prefix belongs to cfengine alone; launchd and runit keep the v4 language); lint overlap, cross-domain and package-uniqueness rules; `report-row` gained `extra_scan`, `two_writers` and `unmet_absence`; cases 113-155. Report-only: v5 prevents no competing write, and the detector itself (S5) is not built. Still deferred: `scope`, externally-written unit, distro family, an inventory schema (spec Q8). |
| 5 | systemd branch of the generic bundle, enforce tests on T1. **Done 2026-10-31 (PR #11):** a present `systemd` entry on a host booted by systemd (`/run/systemd/system`) renders `/etc/systemd/system/<id>` from `policy/templates/systemd.service.mustache`, then `daemon-reload`, `enable`/`disable` per `enabled`, `start` (or `restart` when a running unit changed); a tombstone with a regular unit file present (`isplain`) runs `disable --now`, deletes the file, reloads; a tombstone on an alias link, mask or dangling link is reported (`tombstone not actuated`) and nothing runs (v5 spec S0). State probes are run-cached snapshots, so one run converges and the next issues no `systemctl`. `tests/policy/run.sh` check 6 runs that lifecycle against the real manager on the three ubuntu VM jobs (`TENDCF_TEST_SYSTEMD=1`, passwordless sudo; unit passes `systemd-analyze verify`) and the refusal path on `debian:13` and Darwin; check 4 now uses a runit entry. The prototype's gaps (no restart policy, unescaped argv) closed in step 4 slice A. |
| 6 | nix2cf: systemd renderer (supervisor from inventory), the Linux-relevant `TODO(operator)` markers, the `tendcf.lock` consumer. nix2cf emits only the goal file; Augments stay on the device (`projector.py`). |
| 6 | Compiler (`tendcf compile`, was nix2cf; map D46): systemd renderer (supervisor from inventory; the `plugins/supervisors/systemd` plugin once the split of [`plugin-layout.md`](plugin-layout.md) lands), the Linux-relevant `TODO(operator)` markers. (~~The `tendcf.lock` consumer~~ dropped 2026-11-13: with the compiler in tendcf there is no `tendcf.lock`.) The compiler emits only the goal file; Augments stay on the device (`projector.py`). |
| 7 | T3 dry-run, then one enforced service. **Dry-run done 2026-10-29:** the `debian:13` CI artifact (`cfengine-fork-debian13`, fork `7363abf43`) installed under `~/cf` on pastebin as the unprivileged user; `tests/policy/run.sh` passes all five checks there, and `cf-agent -n` on `examples/host_specific.json` refuses both entries by name (interlock unmet: the example's caddy path is a Mac path; service: `launchd` flavour on `debian_13`) and touches nothing. Found on the way: the artifact needed `librsync`/`libb2` bundled (now done) and the harness had to own its umask (pastebin is 002). **Enforced service, plan decided 2026-10-31:** the canonical CFEngine shape, not a sudoers rule. pastebin's sudo asks for a password and `~/cf` is user-writable, so a passwordless root `cf-agent` there would be an escalation path; CFEngine's own model is a root-owned install and a root `cf-execd` (book ch. 19, 21, 23; [cf-execd](https://docs.cfengine.com/docs/lts/reference/components/cf-execd), [MPF](https://docs.cfengine.com/docs/lts/reference/masterfiles-policy-framework); an unprivileged `cf-agent` cannot do root work, [CFEngine blog](https://cfengine.com/blog/2024/feature-friday-25-unprivileged-execution)), and our v3 design already self-bootstraps each host. Stage A, one password-sudo session: install `/opt/tendcf` root-owned, place the policy and the canary data, one `cf-agent -K -I` run, inspect. Stage B: enable a root `cf-execd`. The canary is `tendcf.canary.service` (`sleep infinity` as `nobody`), its CMDB data a projection of a schema-valid goal file. No masterfiles framework: the installer copies the policy in as root. The CI build now uses `--prefix=/opt/tendcf` so the binaries' library path is root-owned; `tests/deploy/linux-install.sh` runs the full sequence on the ubuntu VMs. Runbook and files: [`deploy/linux/`](../../deploy/linux/README.md). **Done on pastebin 2026-10-31 (tendcf `8f63225`, fork `b8abf2840`):** operator granted root SSH, so the installer ran as root with no sudoers rule left behind. Stage A: canary rendered, enabled, active as `nobody` with `Restart=on-failure`; a second run issued no `systemctl` command. Stage B: a root `cf-execd` (`tendcf-execd.service`) restored the canary within 3 minutes of a manual stop. Found live, invisible to CI (apt installs librsync there): `RUNPATH` on the `cf-*` binaries is not inherited by `libpromises.so`'s own dependencies, so the bundled `librsync`/`libb2` were not found; the installer and the unit now set `LD_LIBRARY_PATH=/opt/tendcf/lib`. The canary is left running under `cf-execd`; its tombstone is the removal path. |
| 8 | T4: the NixOS passthrough adapter (§5), dry-run first. Then T5/T6/T7. **Probe done 2026-10-31, plan proposed:** [`nixos-passthrough-plan.md`](nixos-passthrough-plan.md). vps-primary's `/etc/systemd/system` is a read-only store symlink, so the generic systemd adapter must refuse there (guard first), and the CFEngine build is a derivation in the host flake. |

Expand Down Expand Up @@ -79,11 +79,15 @@ both first-class:
working configuration is ever required.
2. **Nix as an authoring language.** The Site Model's types are also Nix
module options (`mkOption`, `mkIf`, `mkDefault`). A site authored in Nix
evaluates (`nix eval --json --store dummy://`) to the same
schema-validated goal file as one authored in YAML, and nix2cf renders it
for a launchd or systemd host with no Nix installed. The person's Nix
knowledge carries over; Nix the runtime is not needed on the target (D6
unchanged).
evaluates (`nix eval --json --store dummy://` in this plan; the
`eval-nix` hook that exists today runs
`nix-instantiate --eval --strict --json`) to Site Model JSON that
compiles to the same schema-validated goal file as one authored in
YAML, and the compiler renders it for a launchd or systemd host with no
Nix installed. The Nix
frontend is the compiler plugin named `nix2cf` (map D12, D46). The
person's Nix knowledge carries over; Nix the runtime is not needed on
the target (D6 unchanged).

YAML and Nix are equal frontends: each fixture authored in Nix has a YAML
twin, and the two must render to byte-identical goal files. Nobody has to
Expand Down
Loading
Loading