From 080d18fab8818315dd568eeea7582626877f7cbf Mon Sep 17 00:00:00 2001 From: Sam & Claude Date: Thu, 25 Jun 2026 10:41:55 +0200 Subject: [PATCH] =?UTF-8?q?skill(freebsd):=20add=20freebsd-os-upgrade=20?= =?UTF-8?q?=E2=80=94=20minor=20point-release=20runbook?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Ports the verified freebsd-update-reboot.md (reboot-needed detection, pre/post status capture, package/service notes, vuln-audit wording) from clawdie-ai into a layered-soul skill, alongside the existing freebsd-* operational skills. SKILL.md wraps it as the same-major upgrade procedure (15.0 -> 15.1): ABI FreeBSD:15:amd64 unchanged so no package rebuild / no PG dump-restore; reboot only on operator go-ahead; build-host-first sequence; and the clawdie-iso side (bump/override FREEBSD_VERSION, version-agnostic docs). Escalation is host-agnostic (mdo on the operator image, sudo/doas elsewhere). Validation-evidence slot left for the real OSA 15.0->15.1 run to fold in. Co-Authored-By: Claude Opus 4.8 --- skills/freebsd-os-upgrade/SKILL.md | 98 +++++++++++++++++++ .../references/freebsd-update-reboot.md | 96 ++++++++++++++++++ 2 files changed, 194 insertions(+) create mode 100644 skills/freebsd-os-upgrade/SKILL.md create mode 100644 skills/freebsd-os-upgrade/references/freebsd-update-reboot.md diff --git a/skills/freebsd-os-upgrade/SKILL.md b/skills/freebsd-os-upgrade/SKILL.md new file mode 100644 index 0000000..dd2b986 --- /dev/null +++ b/skills/freebsd-os-upgrade/SKILL.md @@ -0,0 +1,98 @@ +--- +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. +--- + +# FreeBSD OS Upgrade (minor / point release) + +How we move a hive node across a FreeBSD point release within the same major +(e.g. `15.0-RELEASE` → `15.1-RELEASE`). Same-major upgrades are low-risk: the +package ABI is unchanged, so no package rebuild and no PostgreSQL dump/restore +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. + +## 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) +freebsd-version -k # installed kernel +freebsd-version -u # installed userland +uname -r # running kernel + +# 2. Upgrade base to the target point release (as root) +freebsd-update -r 15.1-RELEASE upgrade +freebsd-update install # installs new kernel; repeat after reboot + +# 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 +``` + +## When to use + +- A new FreeBSD point release in the current major is available and a node + should track it (OSA / mother, build host, deployed hosts). +- Before building a clawdie-iso image for the new point release (build the + image on a host at the same series). + +## Runbook + +1. **Capture pre-status** for after-the-fact comparison — see + *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. +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). +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.) + +## clawdie-iso image side + +The operator image tracks the series through a single variable. To build for the +new point release: + +```sh +# build.cfg derives the memstick URL, checksum URL, cache path, and +# build-manifest from FREEBSD_VERSION: +FREEBSD_VERSION="${FREEBSD_VERSION:-15.1-RELEASE}" + +# or override per-build without editing git: +FREEBSD_VERSION=15.1-RELEASE ./build.sh +``` + +Docs are kept version-agnostic (`FreeBSD 15.x`) so they don't drift on point +bumps. `build-vps.sh` (mfsbsd) and `scripts/poudriere/poudriere-setup.sh` carry +their own version knobs — bump those separately if that path is in use. + +## Sequence for a release + +Upgrade the build host (OSA) first → refresh its package cache → then build the +image for the new point release, so the image is assembled on a host at the same +series. + +## Validation evidence + + + +- _Pending: OSA `15.0-RELEASE` → `15.1-RELEASE`, — pre/post + `freebsd-version -kru`, services, jails, PF captured and matched._ diff --git a/skills/freebsd-os-upgrade/references/freebsd-update-reboot.md b/skills/freebsd-os-upgrade/references/freebsd-update-reboot.md new file mode 100644 index 0000000..0803f53 --- /dev/null +++ b/skills/freebsd-os-upgrade/references/freebsd-update-reboot.md @@ -0,0 +1,96 @@ +# FreeBSD Base Update Reboot Handoff + +Use this reference after FreeBSD base or package updates, and whenever the +operator asks whether a reboot is required. + +## Reboot-needed rule + +A reboot is required when the installed kernel/userland version is newer than +the running kernel: + +```sh +freebsd-version -k # installed kernel +freebsd-version -u # installed userland +uname -r # running kernel +``` + +If `freebsd-version -k` or `freebsd-version -u` reports a newer patch level than +`uname -r`, the update is staged but not fully active. Report that plainly and +ask the operator for an explicit reboot go-ahead. Reboot only on operator +go-ahead. + +Example interpretation: + +```text +freebsd-version -k: 15.0-RELEASE-p9 +freebsd-version -u: 15.0-RELEASE-p9 +uname -r: 15.0-RELEASE-p8 +``` + +This means the system has p9 installed but is still running a p8 kernel. A reboot +is required to complete the update. + +## Pre-reboot status capture + +Before recommending or handing off a reboot, capture enough state for the next +agent/operator to compare after boot: + +```sh +hostname +freebsd-version -k +freebsd-version -u +uname -r +/usr/sbin/service clawdie status +/usr/sbin/service nginx status +/usr/sbin/service postgresql status +/usr/sbin/jls +/sbin/pfctl -s info +``` + +Use absolute paths for base-system tools when the agent shell has a narrow PATH. +Unprivileged agents may see permission errors for service internals, PostgreSQL, +or PF. Record those as permission-limited checks rather than claiming the service +is down. + +## Package/service considerations + +A same-major PostgreSQL package upgrade, such as `postgresql18-server` 18.3 → +18.4, does not require dump/restore. It still benefits from a reboot or service +restart so the new binaries are loaded. + +If `nginx`, `tailscale`, PostgreSQL, or other long-running daemons were upgraded, +prefer a controlled reboot over piecemeal restarts unless the operator asks for a +minimal-disruption restart plan. + +## Post-reboot verification + +After the operator confirms the host is back, verify: + +```sh +freebsd-version -k +freebsd-version -u +uname -r +/usr/sbin/service clawdie status +/usr/sbin/service nginx status +/usr/sbin/service postgresql status +/usr/sbin/jls +/sbin/pfctl -s info +``` + +Expected after a successful reboot: `freebsd-version -k`, `freebsd-version -u`, +and `uname -r` all report the same patch level. + +Also verify application-specific readiness that matters for the current work: + +- Clawdie control plane reachable/running +- Forgejo reachable if git work is active +- jails are running (`cms`, `worker`, or whatever the host normally owns) +- PF enabled and rules loaded +- Tailscale reachable if remote agents depend on it + +## Vulnerability audit wording + +If `pkg audit` still reports vulnerable packages after an upgrade, do not imply +the upgrade failed. Say that the applied upgrade completed, but unrelated +packages remain vulnerable until fixed packages are available or the operator +chooses a ports/package remediation path.