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 15.1-RELEASE
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 pkg web upgrade -f
A forced package upgrade is appropriate across a major FreeBSD ABI transition. Review its transaction before confirmation and then verify the services, listener addresses, mounts, DNS, and 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 pkg web upgrade -f
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.