Synopsis #
An update applies security and errata fixes within one FreeBSD release. An upgrade moves a jail to another release. Bastille handles thin and thick jails differently: thin jails share a bootstrapped release, while a thick jail carries its own userland.
Identify the jail type before choosing a command. Back up the jail and its separately mounted data, review the target release notes, and upgrade the host before any jail that will use the newer release. A jail userland must not be newer than its host kernel.
Inventory the boundary #
Record the host, Bastille, releases, jail types, packages, mounts, and inbound mappings:
$ freebsd-version -ku
$ pkg info bastille
# bastille list release
# bastille list jail
# bastille list all
# bastille rdr ALL list
For each important jail, also record its service state and package set:
# bastille cmd web freebsd-version
# bastille cmd web pkg info
# bastille cmd web service -e
A rollback requires more than the jail root. Follow Back up and restore a Bastille jail , and separately protect datasets mounted as described in Mount a ZFS dataset in a Bastille jail .
Apply patches within a release #
For a thin jail, update the shared bootstrapped release:
# bastille update 15.1-RELEASE
Every thin jail based on that release sees the updated base. Restart affected jails so that long-running processes and services use the updated files:
# bastille restart web
For a thick jail, target the jail itself:
# bastille update web
# bastille restart web
Base-system patching does not update third-party packages. Review and apply package changes separately:
# bastille pkg web update
# bastille pkg web upgrade
The choice between official packages, ports, and a private repository is covered in Choose packages, ports, or poudriere .
Plan a release upgrade #
Before moving to another release:
- Confirm that the target is supported and that the host already runs it or a newer release.
- Read the target release notes and errata.
- Update the source release to its latest patch level.
- Verify backups and a restore destination.
- Schedule downtime for stateful services.
- Upgrade one representative jail before applying the change to a group.
Do not destroy the old bootstrapped release until all jails, package ABIs, services, and restore procedures have been verified.
Upgrade a thin jail #
Bootstrap and patch the target release. FreeBSD 15 uses pkgbase-aware Bastille workflows; follow the installed Bastille documentation for how the source jail was created and do not silently change its base-management method.
For a conventional thin jail moving from a supported 14.x release to 15.1, the lifecycle is:
# bastille bootstrap 15.1-RELEASE
# bastille update 15.1-RELEASE
# bastille stop web
# bastille upgrade web 15.1-RELEASE
# bastille etcupdate bootstrap 15.1-RELEASE
# bastille etcupdate web update 15.1-RELEASE
# bastille etcupdate web diff
The etcupdate bootstrap step downloads release source and builds a configuration baseline. Allow space for the source tree under the Bastille prefix and temporary build files under /tmp; this can take longer than switching the jail’s release mount.
Resolve /etc conflicts deliberately. The resolve action can change files and should follow review of the diff:
# bastille etcupdate web resolve
# bastille start web
# bastille cmd web /usr/local/sbin/pkg-static upgrade -f
# bastille restart web
A major FreeBSD ABI transition requires replacement packages. The old dynamically linked pkg can fail with a missing shared library after the new base is mounted; the installed pkg-static can perform that transition without those old libraries. Review its transaction before confirmation. Restart the jail afterward so services that could not start with the old packages, or still loaded old libraries, use the replacement packages.
Review configuration-update warnings as well as conflicts, complete any requested database regeneration, and verify services, listener addresses, mounts, DNS, and the external path.
For a thin pkgbase jail, use the pkgbase-specific bootstrap and upgrade procedure in the current Bastille upgrading documentation. Do not mix legacy release archives and pkgbase assumptions in one copied command sequence.
Upgrade a thick jail #
The traditional thick-jail sequence is two-stage:
# bastille upgrade web 15.1-RELEASE
# bastille upgrade web install
# bastille restart web
# bastille upgrade web install
Across a major release boundary, reinstall or upgrade packages after the base upgrade:
# bastille cmd web /usr/local/sbin/pkg-static upgrade -f
# bastille restart web
Current pkgbase thick jails use a shorter Bastille sequence. Establish whether the jail is legacy or pkgbase-backed from its creation record and current Bastille documentation before applying either procedure.
Verify before removing the old release #
Check both administrative and application state:
# bastille cmd web freebsd-version
# bastille cmd web pkg check -d
# bastille cmd web service -e
# bastille rdr web list
Test every published service from its intended client network. Confirm separately mounted datasets and scheduled jobs. Retain the old release and backups through an observation period; downgrade of a thick jail is not a supported recovery strategy.