clawdie/layered-soul
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

skill(freebsd): cover pkgbase (OSA) alongside freebsd-update

Browse source 
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_<N>/base_latest crosses a point
  release), then pkg update && pkg upgrade (base + ports together).
- freebsd-update: freebsd-update -r <target> 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 <noreply@anthropic.com>
This commit is contained in:
Sam & Claude 2026-06-25 10:47:31 +02:00
parent 080d18fab8
commit 73304e7f41
1 changed files with 49 additions and 22 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

71
skills/freebsd-os-upgrade/SKILL.md
View file

@ -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_<N> 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 <target> 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_<N>` /
`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 <target> 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.
<!-- Filled from a real run. Fold in the captured freebsd-version output,
service/jail/PF status, and any deviations. -->
- _Pending: OSA `15.0-RELEASE` → `15.1-RELEASE`, <DD.mon.YYYY> — 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 (<DD.mon.YYYY>) — confirm the base
repo targets 15.1, then fold in pre/post `freebsd-version -kru`, services,
jails, PF._