Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

0012 — Boot-environment naming convention (stem + UTC stamp)

Status: accepted (2026-06-22) — ratified by maintainer; proposed 2026-06-05

Context

The install default names the BE <pool>/ROOT/<distro> (e.g. rpool/ROOT/gentoo), but keyboot-be-upgrade already names its clone <be>-<UTCstamp> (date -u +%Y-%m-%d-%H%MZ, matching ADR 0006’s snapshot stamp) → rpool/ROOT/gentoo-2026-06-05-1823Z. So after the first upgrade a host has a mixed convention: gentoo next to gentoo-2026-…Z.

Worse, the upgrade tool derives the clone leaf from ${BE##*/} — the full leaf, including any existing stamp — so a second upgrade produces gentoo-2026-06-05-1823Z-2026-07-01-0900Z: the stamp stacks. (Latent today because the install BE is unstamped; it bites on the second upgrade.)

Decision

Canonical BE name: <pool>/ROOT/<stem>-<YYYY-MM-DD-HHMM>Z — UTC with an explicit Z, identical to ADR 0006’s snapshot stamp (so BE and snapshot times read the same, and sort within a stem is chronological).

  • <stem> is the stable human anchor, carried across the BE’s whole upgrade lineage. It defaults to the distro (gentoo); install-os --be-label <stem> overrides it (e.g. gentoo-prod / gentoo-test) so one host can run differently-purposed lineages. (Parameterize with a sensible default.)
  • Re-stamp the stem, never append. Upgrade/rollback derive the stem by stripping a trailing -<YYYY-MM-DD-HHMM>Z from the current leaf, then add a fresh stamp: gentoo-<old>Z → gentoo-<new>Z, not …-<old>Z-<new>Z.
  • --be <full-dataset> still overrides everything (no stamp added) for operators who want a plain rpool/ROOT/gentoo.
  • Provenance lives in ZFS user properties, not the name: keyboot:origin= install|upgrade|rollback, keyboot:created=<UTC>, and for rollbacks keyboot:rolled-back-from=<snapshot>. Names stay short + sortable; keyboot-install be list surfaces origin/when/active. “Which is current” is bootfs + keyboot’s picker — the name never encodes it.

The convention is specified once here and implemented by a small pure helper pair (keyboot_be_stem / keyboot_be_make_name, lib/benaming.sh, bats-tested). Because the install orchestrator (rescue env) and the keyboot-be-* tools (booted BE) run in different runtime contexts that can’t always share a sourced lib, the stem-strip is mirrored inline in the tools — this ADR is the canonical spec they track.

Alternatives considered

  • Keep <distro> for the install BE, stamp only clones — rejected: that’s the current mixed convention; the first BE stays the special-case “no stamp”.
  • Stem = always the distro (no custom label) — rejected as too rigid; a host may want app-prod / app-test lineages. The label is optional (defaults to distro), so simple hosts are unaffected.
  • Provenance in the name (-upgrade / -rb-<tag> suffixes) — rejected: bloats names and breaks chronological sort; user properties are queryable and keep the name a clean <stem>-<UTC>Z.

Consequences

  • Fixes the stamp-stacking bug in keyboot-be-upgrade (re-stamp the stem).
  • Staged rollout (avoids one risky change to the CI-verified install path):
    1. done (b42d46f) — locked the convention, shipped lib/benaming.sh + tests, fixed the upgrade stem-strip.
    2. done (GL#36) — flipped the install-os default BE to <stem>-<UTC>Z, added --be-label, aligned keyboot-be-rollback’s clone naming to <stem>-<UTC>Z + keyboot:origin/keyboot:rolled-back-from provenance props. KEYBOOT_BE_STAMP pins the stamp for deterministic installs/tests; the QEMU harnesses already pin --be explicitly, so the default flip doesn’t ripple into them.
  • keyboot-install be list becomes the place “which BE, when, how made, which is active” is answered (origin/created/bootfs), since the name no longer carries provenance.