From 73304e7f4127fd31b3dcdb9e6ac0c8a636ce68e3 Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Thu, 25 Jun 2026 10:47:31 +0200 Subject: [PATCH] skill(freebsd): cover pkgbase (OSA) alongside freebsd-update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OSA manages its base via pkgbase (FreeBSD-kernel-generic 15.0p10), not freebsd-update — the two are mutually exclusive. Add a detection step (pkg info -e FreeBSD-runtime) and branch the upgrade procedure: - pkgbase: confirm the base repo targets the new series (a pinned base_release_0 only delivers patch levels; base_release_/base_latest crosses a point release), then pkg update && pkg upgrade (base + ports together). - freebsd-update: freebsd-update -r upgrade/install + pkg for ports. Reboot detection, verification, and the clawdie-iso side are identical for both. Fold in OSA partial evidence: pre-status clean (k/u/uname all matched). Co-Authored-By: Claude Opus 4.8 --- skills/freebsd-os-upgrade/SKILL.md | 71 +++++++++++++++++++++--------- 1 file changed, 49 insertions(+), 22 deletions(-) diff --git a/skills/freebsd-os-upgrade/SKILL.md b/skills/freebsd-os-upgrade/SKILL.md index dd2b986..0d05f40 100644 --- a/skills/freebsd-os-upgrade/SKILL.md +++ b/skills/freebsd-os-upgrade/SKILL.md @@ -1,6 +1,6 @@ --- name: freebsd-os-upgrade -description: Minor (same-major) FreeBSD upgrade runbook for hive nodes — freebsd-update, reboot-needed detection, pre/post verification, and the clawdie-iso FREEBSD_VERSION bump. +description: Minor (same-major) FreeBSD upgrade runbook for hive nodes — pkgbase or freebsd-update, reboot-needed detection, pre/post verification, and the clawdie-iso FREEBSD_VERSION bump. --- # FreeBSD OS Upgrade (minor / point release) @@ -12,27 +12,45 @@ are required. The detailed reboot rules and verification live in [`references/freebsd-update-reboot.md`](references/freebsd-update-reboot.md); this is the procedure that wraps them. +A host manages its base system one of two **mutually exclusive** ways — detect +which before upgrading: + +- **pkgbase** — base installed via `pkg` (you'll see `FreeBSD-*` packages like + `FreeBSD-kernel-generic`). Upgrade with `pkg`. This is OSA's method. +- **freebsd-update** — binary base updates via `freebsd-update(8)`. + +Detect: `pkg info -e FreeBSD-runtime && echo pkgbase || echo freebsd-update`. +Reboot detection, verification, and the clawdie-iso side are identical for both; +only the "fetch + install the new base" step differs. + ## Quick reference Run the privileged steps as root, or via the host's escalation — `mdo` on the operator image, `sudo`/`doas` elsewhere. ```sh -# 1. Detect current state (installed vs running) +# 0. Which base-management method? (mutually exclusive) +pkg info -e FreeBSD-runtime && echo "pkgbase" || echo "freebsd-update" + +# 1. Detect installed vs running kernel (both methods) freebsd-version -k # installed kernel freebsd-version -u # installed userland uname -r # running kernel -# 2. Upgrade base to the target point release (as root) +# 2a. pkgbase (base via pkg, e.g. FreeBSD-kernel-generic): +# confirm the base repo points at the TARGET series first — a release-pinned +# repo (base_release_0) only delivers patch levels; base_release_ or +# base_latest is what moves you across a point release. Then: +pkg update +pkg upgrade # upgrades base AND ports packages together + +# 2b. freebsd-update (binary base updates): freebsd-update -r 15.1-RELEASE upgrade -freebsd-update install # installs new kernel; repeat after reboot +freebsd-update install # stages new kernel; run again after reboot +pkg update -f && pkg upgrade # ports packages (separate from base here) -# 3. Reboot ONLY on operator go-ahead, then (as root): -freebsd-update install # finish userland after the new kernel boots - -# 4. Refresh packages (same major — ABI FreeBSD:15:amd64 is unchanged) -pkg update -f -pkg upgrade +# 3. Reboot ONLY on operator go-ahead — a new kernel is staged until reboot. +# Same major: ABI FreeBSD:15:amd64 unchanged, no rebuild / no PG dump-restore. ``` ## When to use @@ -48,19 +66,25 @@ pkg upgrade *Pre-reboot status capture* in the reference (hostname, `freebsd-version -kru`, services, `jls`, `pfctl -s info`). Record permission-limited checks as such, not as "down". -2. **Upgrade base**: `freebsd-update -r upgrade` then - `freebsd-update install`. The new kernel is staged; the system still runs the - old one until reboot. +2. **Upgrade base** (by the method from step 0): + - **pkgbase**: confirm the base repo targets the new series first — repoint + `FreeBSD-base` from a pinned `base_release_0` to `base_release_` / + `base_latest` if needed (a pinned release repo only delivers patch levels), + then `pkg update && pkg upgrade` (base + ports together). + - **freebsd-update**: `freebsd-update -r upgrade` then + `freebsd-update install`. + Either way the new kernel is staged; the system runs the old one until reboot. 3. **Confirm a reboot is needed**: `freebsd-version -k` newer than `uname -r` means staged-not-active. State that plainly and **reboot only on explicit operator go-ahead** — never reboot the always-on board host autonomously. -4. **After reboot**: run `freebsd-update install` again to finish userland, then - the *Post-reboot verification* block — `-k`/`-u`/`uname -r` must all match, - and the app-readiness checks (Clawdie control plane, Forgejo, jails, PF, - Tailscale) must pass. -5. **Packages**: `pkg update -f && pkg upgrade`. Same-major ABI is unchanged, so - this is a freshness refresh, not a rebuild. A same-major PostgreSQL bump needs - no dump/restore (restart/reboot to load new binaries). +4. **After reboot**: on freebsd-update hosts, run `freebsd-update install` again + to finish userland. Then the *Post-reboot verification* block — `-k`/`-u`/ + `uname -r` must all match, and the app-readiness checks (Clawdie control + plane, Forgejo, jails, PF, Tailscale) must pass. +5. **Packages**: same-major ABI (`FreeBSD:15:amd64`) is unchanged, so this is a + freshness refresh, not a rebuild — pkgbase already covered it in step 2; + freebsd-update hosts do `pkg update -f && pkg upgrade`. A same-major + PostgreSQL bump needs no dump/restore (restart/reboot to load new binaries). 6. **Vulnerability audit**: if `pkg audit` still flags packages, do not imply the upgrade failed — the upgrade completed; unrelated packages remain vulnerable until fixed versions land. (Wording in the reference.) @@ -94,5 +118,8 @@ series. -- _Pending: OSA `15.0-RELEASE` → `15.1-RELEASE`, — pre/post - `freebsd-version -kru`, services, jails, PF captured and matched._ +- **OSA** uses **pkgbase** (`FreeBSD-kernel-generic 15.0p10`). Pre-status clean: + `freebsd-version -k`, `-u`, and `uname -r` all matched — no pending reboot. + _Pending: `15.0 → 15.1` post-upgrade capture () — confirm the base + repo targets 15.1, then fold in pre/post `freebsd-version -kru`, services, + jails, PF._