skills/freebsd-os-upgrade/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: freebsd-os-upgrade
-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.
+description: Minor (same-major) FreeBSD upgrade runbook for hive nodes — pkgbase or freebsd-update, reboot-needed detection, Bastille thin/thick jail upgrade, pre/post verification, and the clawdie-iso FREEBSD_VERSION bump.
 ---
 
 # FreeBSD OS Upgrade (minor / point release)
@@ -94,9 +94,43 @@ pkg update -f && pkg upgrade      # ports packages (separate from base here)
    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.)
+6. **Upgrade the jails** — the host upgrade does NOT touch them. Do this after
+   the host is on the new kernel. See *Jails* below.
+7. **Vulnerability audit**: if `pkg audit` still flags packages (host or jails),
+   do not imply the upgrade failed — the upgrade completed; unrelated packages
+   remain vulnerable until fixed versions land. (Wording in the reference.)
+
+## Jails
+
+Jails carry their **own userland** — a host base upgrade leaves them on the old
+release. Upgrade them as part of the same process, **after** the host is on the
+new kernel (jails run on the host kernel; a same-major userland mismatch is
+tolerated, but move them up for consistency + security). OSA uses **Bastille**
+(`/usr/local/bastille/jails/`).
+
+- **Thick jail** — a full, independent base copy. Upgrade each on its own.
+- **Thin jail** — a clone/overlay of a bootstrapped release template. Bootstrap
+  the new release once, then bring each thin jail up off it.
+
+Each jail's base is managed the same two ways as the host — detect per jail:
+`bastille cmd <jail> pkg info -e FreeBSD-runtime` (pkgbase) vs freebsd-update.
+
+Bastille flow (confirm against the installed Bastille version + bootstrap method):
+
+```sh
+bastille list                                # jails, thin/thick
+# freebsd-update-managed jails:
+bastille bootstrap 15.1-RELEASE              # new release template (for thin)
+bastille upgrade <jail> 15.1-RELEASE
+# pkgbase-managed jail: repoint its base repo (edit-existing, not append),
+#   then  bastille pkg <jail> upgrade
+bastille cmd <jail> freebsd-version          # verify each jail moved to 15.1
+```
+
+Same-major ABI (`FreeBSD:15:amd64`) is unchanged, so packages inside jails need
+no rebuild — `bastille pkg <jail> upgrade` is a freshness refresh. Restart each
+jail (or its services) so new binaries load, then re-check `jls` and per-jail
+service health from the reference's *Post-reboot verification*.
 
 ## clawdie-iso image side
 
@@ -130,5 +164,6 @@ series.
 - **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._
+  repo targets 15.1; fold in host pre/post `freebsd-version -k`/`-u` + `uname -r`,
+  services, PF, and **per-jail** `bastille cmd <jail> freebsd-version` after each
+  jail is upgraded (record thin/thick + bootstrap method per jail)._