Date: Wed, 19 Nov 2025 10:26:00 +0000 From: Benedict Reuschling <bcr@FreeBSD.org> To: doc-committers@FreeBSD.org, dev-commits-doc-all@FreeBSD.org Cc: Lukas Engelhardt <lukas.engelhardt@gmx.de> Subject: git: 099e57c42a - main - cutting-edge: Include boot environment use in a major upgrade with pkgbase Message-ID: <691d9b38.3e59d.68966e41@gitrepo.freebsd.org>
index | next in thread | raw e-mail
The branch main has been updated by bcr: URL: https://cgit.FreeBSD.org/doc/commit/?id=099e57c42ac62b6792267a3bff501fe8179b0571 commit 099e57c42ac62b6792267a3bff501fe8179b0571 Author: Lukas Engelhardt <lukas.engelhardt@gmx.de> AuthorDate: 2025-11-19 10:16:45 +0000 Commit: Benedict Reuschling <bcr@FreeBSD.org> CommitDate: 2025-11-19 10:25:44 +0000 cutting-edge: Include boot environment use in a major upgrade with pkgbase Explain the major version upgrade procedure with ZFS boot environments as an extra safety net in case something goes wrong. Add a workaround for a problem that may remove pkg itself in some edge cases. Remove older, unsupported 14.2-RELEASE from the instructions. Reviewed by: bcr, Graham Perrin <grahamperrin@gmail.com> Differential Revision: https://reviews.freebsd.org/D53534 --- .../en/books/handbook/cutting-edge/_index.adoc | 206 +++++++++++++++------ 1 file changed, 147 insertions(+), 59 deletions(-) diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc index bb583c1185..2f813b3419 100644 --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1088,35 +1088,46 @@ The last step after updating is to restart the computer so all the changes take .... [[pkgbase]] -== Updating FreeBSD with Base System Packages +== Updating FreeBSD with packages -Starting from 14.0-RELEASE, the FreeBSD project has published a set of packages of the kernel and base system, using man:pkg[8]. -These can be used in the same convenient way that users are used to, for adding and upgrading ported software, but for the kernel and userland itself. -The packages, and usage thereof, are often referred to as pkgbase. +Starting from 14.0-RELEASE, the FreeBSD project has published a set of packages of the base system, using man:pkg[8]. +The convenience of pkg is no longer limited to the FreeBSD ports collection. +man:pkg[8] can be used for FreeBSD itself. +Base packages, and usage thereof, were traditionally referred to as _pkgbase_. -Packages have been available since link:https://lists.freebsd.org/archives/freebsd-pkgbase/2023-October/000221.html[October 2023], considered experimental for FreeBSD's 14 Release. +Publication of official packages began in link:https://lists.freebsd.org/archives/freebsd-pkgbase/2023-October/000221.html[October 2023]. +Their use with FreeBSD 14 is currently experimental. -Starting from 15.0-RELEASE, Base System packages will be the default and officially supported way to both install new FreeBSD instances, and also to update and upgrade between minor and major releases. +Starting from 15.0-RELEASE, man:freebsd-base[7] will be supported as a tech preview for: -[NOTE] -==== -From 15.0-RELEASE onwards, the long-running man:freebsd-update[8] tool will only be supported on the earlier 13 and 14 release branches. -==== +* installation +* minor upgrades +* major upgrades -Base System Packages replace: +freebsd-base will eventually replace: * tarball distribution sets, such as `base.txz` or `kernel.txz`, which are historically used for installation of the OS with man:bsdinstall[8] * man:freebsd-update[8] for updates to the OS. +The current plan is for freebsd-update to work with pkg. + +[WARNING] +==== +The replacement of distribution sets will take some time, until freebsd-base is fully stable! +==== + Base System packages complement crossref:cutting-edge[makeworld,"building and installing from source"], which is still available for those who wish to build their own custom kernels or userland. It is also possible to build custom base system packages from local sources, as well as just relying on officially provided packages. -=== Converting a Host to use pkgbase +=== Converting a Host to use freebsd-base + +FreeBSD 14.0-RELEASE or later can be converted to use base packages. +Earlier versions must be upgraded with freebsd-update before conversion. -Systems installed with FreeBSD 14.0-RELEASE or later can be converted to use Base System packages. -For earlier versions, it is recommended to first upgrade to a recent Version, and then convert. +For conversion, the FreeBSD Foundation-sponsored link:https://github.com/FreeBSDFoundation/pkgbasify[pkgbasify] tool is recommended. +Follow the instructions given there. -The FreeBSD Foundation has sponsored development of a tool called link:https://github.com/FreeBSDFoundation/pkgbasify[pkgbasify], which for most users, will be the easiest and safest way to convert systems to use Base System packages. +man:freebsd-update[8] will be enhanced to use pkg and pkgbasify. [WARNING] ==== @@ -1133,19 +1144,11 @@ man:pkgbasify[8] (or whatever outcome link:https://reviews.freebsd.org/D51594[D5 * Updates passwd and capabilities databases * Restarts sshd immediately -[source,shell] -.... -# cd /tmp -# fetch https://github.com/FreeBSDFoundation/pkgbasify/raw/refs/heads/main/pkgbasify.lua -# chmod +x pkgbasify.lua -# ./pkgbasify.lua -.... - -=== Upgrading a Host using pkgbase +=== Upgrading a Host using freebsd-base [WARNING] ==== -This is still in development, so please be careful especially when converting an existing system to use pkgbase. +This is still in development, so please be careful especially when converting an existing system to use freebsd-base. ==== Create a folder for custom pkg repository config files, if there is none present already. @@ -1155,7 +1158,7 @@ Create a folder for custom pkg repository config files, if there is none present # mkdir -p /usr/local/etc/pkg/repos/ .... -For using the pkgbase repository, create a pkg repository configuration file called `FreeBSD-base.conf`: +For using the freebsd-base repository, create a pkg repository configuration file called `FreeBSD-base.conf`: [[pgk-base-repo-configuration]] [.programlisting] @@ -1183,27 +1186,35 @@ There are different branches to choose from (by changing the url accordingly): | main | twice daily - 12:00 and 00:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_latest` +| `pkg+https://pkg.freebsd.org/${ABI}/base_latest` | main | weekly – Sunday at 12:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_weekly` +| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly` | stable/14 | twice daily – 12:00 and 00:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_latest` +| `pkg+https://pkg.freebsd.org/${ABI}/base_latest` | stable/14 | weekly – Sunday at 12:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_weekly` +| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly` -| releng/14.2 +| releng/14.3 | twice daily – 12:00 and 00:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_release_2` +| `pkg+https://pkg.freebsd.org/${ABI}/base_release_3` -| releng/14.3 +| releng/15.0 | twice daily – 12:00 and 00:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_release_3` +| `pkg+https://pkg.freebsd.org/${ABI}/base_release_0` + +| stable/15 +| twice daily – 12:00 and 00:00 UTC +| `pkg+https://pkg.freebsd.org/${ABI}/base_latest` + +| stable/15 +| weekly – Sunday at 12:00 UTC +| `pkg+https://pkg.freebsd.org/${ABI}/base_weekly` |=== To upgrade the system, change the configuration file according to the desired release, and run: @@ -1223,17 +1234,45 @@ Reboot the OS executing the following command: # shutdown -r now .... -==== Performing Major version upgrades +[[pkgbase-major-upgrade]] +==== Major Upgrades +With ZFS, boot environments allow an upgrade to be performed without interrupting running software. +If the system does not use root-on-ZFS: backup before upgrading. + +===== Preparations +Change `/usr/local/etc/pkg/repos/FreeBSD-base.conf` to target the correct major release like `base_release_0` for 15.0-RELEASE, to look like this: -When running ZFS, consider creating a boot environment before upgrading to a newer version. -To create a new boot environment using the man:bectl[8] tool run: +[WARNING] +==== +This file might change to be included in RELEASE with a different path. +==== + +[.programlisting] +.... +FreeBSD-base { + url = "pkg+https://pkg.freebsd.org/${ABI}/base_release_0"; + mirror_type = "srv"; + signature_type = "fingerprints"; + fingerprints = "/usr/share/keys/pkg"; + enabled = yes; +} +.... + +[WARNING] +==== +As pkgbase with FreeBSD 14 is experimental, so is a pkgbase major upgrade to 15. +At the time of this writing in some edge-cases the major upgrade removes pkg and therefore segfaults. +This is considered a (link:https://github.com/freebsd/pkg/issues/2475[known issue]) for 15.0-RELEASE. +To work around this issue, lock pkg before upgrading. [source,shell] .... -# bectl create 14.2-RELEASE-p4 +# pkg -c /mnt/upgrade lock pkg .... -Use this boot environment to start the system as it was before the update if something goes wrong. +An experimental major upgrade from FreeBSD 14, to 15 (or 16.0-CURRENT), should be followed by installation of meta package `FreeBSD-set-minimal`. +==== + Save a list of the non-base packages in case they are needed later: @@ -1242,27 +1281,78 @@ Save a list of the non-base packages in case they are needed later: pkg prime-origins | sort -u > /var/tmp/pkg-prime-origins.txt .... -Change `/usr/local/etc/pkg/repos/FreeBSD-base.conf` to target the correct major release like `base_latest`, so it looks like: +[[pkgbase-major-zfs]] +===== major upgrade with zfs +Create a boot environment using man:bectl[8] and name it according to the version upgrading to +[source,shell] +.... +# bectl create 15.0-RELEASE +.... -[.programlisting] +Create a directory then mount the new boot environment there to enable working with pkg man:chroot[8] and rootdir. + +[source,shell] .... -FreeBSD-base { - url = "pkg+https://pkg.freebsd.org/${ABI}/base_latest"; - mirror_type = "srv"; - signature_type = "fingerprints"; - fingerprints = "/usr/share/keys/pkg"; - enabled = yes; -} +# mkdir /mnt/upgrade +# bectl mount 15.0-RELEASE /mnt/upgrade .... -The next step will upgrade the system to the specified version. +The next step will upgrade the boot environment to the specified version. [WARNING] ==== This step might remove non-base packages, which could include the running desktop environment. -Be careful. ==== +Set the environment variable ABI to upgrade the major version (replace amd64 with the architecture and 15 with the targeted version). +Set the pkg-static chroot directory to the boot environment mountpoint. + +[source,shell] +.... +# env ABI=FreeBSD:15:amd64 pkg-static -c /mnt/upgrade upgrade -r FreeBSD-base +.... + +There will be a prompt asking about ignoring the version mismatch looking like this: + +[source,shell] +.... +Newer FreeBSD version for package FreeBSD-zoneinfo: +To ignore this error set IGNORE_OSVERSION=yes +- package: 1500058 +- running userland: 1500000 +Ignore the mismatch and continue? [y/N]: +.... + +Check and confirm that. + +To check if that was successful, chroot into the mountpoint of the boot environment and run `freebsd-version -kru`. + +[source,shell] +.... +# chroot /mnt/upgrade +# freebsd-version -ku +# exit +.... + +Activate the boot environment temporarily and reboot. +[source,shell] +.... +# bectl activate -t 15.0-RELEASE +# shutdown -r now +.... + +If the system does not work as expected: restart the OS to cease using the temporarily active boot environment. +The next boot will reuse the pre-upgrade environment. + +If the system runs stable after reboot, don't forget to permanently activate this boot environment to prevent accidentally booting the old system. + +[source,shell] +.... +bectl activate 15.0-RELEASE +.... + +[[pkgbase-major-non-zfs]] +===== major upgrade without zfs Set the environment variable ABI to upgrade the major version (replace amd64 with the architecture and 15 with the targeted version). [source,shell] @@ -1283,27 +1373,25 @@ Ignore the mismatch and continue? [y/N]: Check and confirm that. -To check if that was successful, run `freebsd-version -kru`. +To check if the upgrade was successful, run `freebsd-version -ku`. Then reboot. -After upgrading to a new major version, updates and upgrades of installed packages to match the ABI version may be necessary. - +===== Post-upgrade tasks +If pkg was locked during the update as a workaround remove the lock like this: [source,shell] .... -# pkg update -# pkg upgrade +# pkg unlock pkg .... -If something broke, go back and activate the backup boot environment created before. +After upgrading to a new major version, updates and upgrades of installed packages to match the ABI version may be necessary. [source,shell] .... -# bectl activate 14.2-RELEASE-p4 +# pkg upgrade .... -Reboot, and the system will be back to the state before upgrading. -If no boot environment was created before, consider getting help from link:https://www.freebsd.org/support/[FreeBSD Support]. +Consider getting help from link:https://www.freebsd.org/support/[FreeBSD Support] when experiencing issues. [[build-pkgbase-packages-locally]] === Manually building pkgbase and publishing it to the local networkhelp
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?691d9b38.3e59d.68966e41>