From 91d204cb9e520196ca49b1ae5d7f7d40fae58109 Mon Sep 17 00:00:00 2001 From: VirtualMachinist Date: Fri, 30 Oct 2026 19:01:12 -0400 Subject: [PATCH] docs: add root-custody upgrade runbook (lock and switch) --- docs/custody-upgrade-runbook.md | 55 +++++++++++++++++++++++++++++++++ docs/install.md | 5 +++ 2 files changed, 60 insertions(+) create mode 100644 docs/custody-upgrade-runbook.md diff --git a/docs/custody-upgrade-runbook.md b/docs/custody-upgrade-runbook.md new file mode 100644 index 00000000..3d4d5eaa --- /dev/null +++ b/docs/custody-upgrade-runbook.md @@ -0,0 +1,55 @@ +# Root-custody upgrade runbook + +Use this to upgrade a `facet` binary installed under a root-owned prefix (``), where the live binary is the symlink `/bin/facet` → `/facet//facet` and the command allowlist lives at `/etc/allow-cmds.json`. Every version stays in its own directory, so rollback is a symlink switch. + +## Run order + +1. **Verify the release.** `gh attestation verify --repo Hedronite/facet` must pass. After you extract the archive, record `shasum -a 256 facet` and check it against the attested release digest (`SHA256SUMS`, which is attested too). +2. **Install under the root prefix.** Put the binary at `$D/facet//facet` (root-owned) and stage the allowlist that matches the version. +3. **Lock and switch** (block below). +4. **Post-checks** (below). Do not go on until every check passes. +5. **Smokes and QA.** Run `facet --version`, `facet doctor --json`, and your usual smoke runs against the live path. +6. **Announce downstream.** Tell dependent hosts or users that `` is live. + +## Lock and switch + +```bash +D= # root-owned install prefix +A=> +sudo chflags schg $D/facet//facet # make the new binary system-immutable so nothing can modify it in place +sudo ln -sfh $D/facet//facet $D/bin/facet # atomic switch of the live symlink; the previous version stays on disk for rollback +sudo install -o root -g wheel -m 0444 $A $D/etc/allow-cmds.json # version-matched allowlist, root-owned and read-only +sudo -k # drop the cached sudo credential +ls -l $D/bin/facet # quick look at where the link points +``` + +The symlink and the allowlist must move together. If only the symlink moves, the host is left **half-switched**: the new binary runs against the old version's allowlist. + +## Post-checks + +```bash +readlink $D/bin/facet # must print $D/facet//facet +ls -lO $D/facet//facet # flags column must show schg +shasum -a 256 $D/etc/allow-cmds.json "$A" # the two digests must match +shasum -a 256 $D/facet//facet # must match the attested release digest +``` + +**If any check fails, stop.** Fix it (most often by rerunning the `install` line) and run every post-check again before you start the smokes. + +## Rollback + +```bash +sudo ln -sfh $D/facet//facet $D/bin/facet +sudo install -o root -g wheel -m 0444 > $D/etc/allow-cmds.json +sudo -k +``` + +Then run the post-checks again, using `` and its allowlist. + +Rollback does not need `sudo chflags noschg`. You only need that to remove or delete a version directory. + +## Platform note + +`chflags`, `ls -lO`, and `ln -h` are BSD/macOS forms, and `wheel` is the macOS root group. This runbook covers macOS root custody only. + +See also: [Install](install.md). diff --git a/docs/install.md b/docs/install.md index f47e077a..ba9f4212 100644 --- a/docs/install.md +++ b/docs/install.md @@ -118,6 +118,10 @@ facet doctor --json # machine + workspace stores, secrets backend, env flag `facet doctor` reports whether Lattice stores open, schema versions, and which `FACET_*` environment variables are set. Use it after install or when debugging a new machine. +### Root-owned installs + +If you run `facet` from a root-owned prefix with a version-matched command allowlist, follow the [root-custody upgrade runbook](custody-upgrade-runbook.md) to lock, switch, check, and roll back. + ## Versions Facet carries three version axes. They are allowed to differ; each simply has @@ -139,4 +143,5 @@ tag, the Cargo version, and the built binary in agreement. - Product overview: [README](../README.md) - Facet commands and JSON contracts: [FACET.md](FACET.md) +- Root-custody upgrades: [custody-upgrade-runbook.md](custody-upgrade-runbook.md) - Engine configuration: [LATTICE-ENGINES.md](LATTICE-ENGINES.md)