diff --git a/documentation/content/en/books/handbook/cutting-edge/_index.adoc b/documentation/content/en/books/handbook/cutting-edge/_index.adoc --- a/documentation/content/en/books/handbook/cutting-edge/_index.adoc +++ b/documentation/content/en/books/handbook/cutting-edge/_index.adoc @@ -1197,13 +1197,17 @@ | weekly – Sunday at 12:00 UTC | `https://pkg.freebsd.org/${ABI}/base_weekly` -| releng/14.2 -| twice daily – 12:00 and 00:00 UTC -| `https://pkg.freebsd.org/${ABI}/base_release_2` - | releng/14.3 | twice daily – 12:00 and 00:00 UTC | `https://pkg.freebsd.org/${ABI}/base_release_3` + +| stable/15 +| twice daily – 12:00 and 00:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_latest` + +| stable/15 +| weekly – Sunday at 12:00 UTC +| `https://pkg.freebsd.org/${ABI}/base_weekly` |=== To upgrade the system, change the configuration file according to the desired release, and run: @@ -1223,18 +1227,25 @@ # shutdown -r now .... +[[pkgbase-major-upgrade]] ==== Performing Major version upgrades +When running ZFS, boot environments are an easy option to upgrade the system without interrupting running software and then upgrade into the upgraded system. +When not running ZFS, consider backing up the system before upgrading to a newer version. -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: +===== 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: -[source,shell] +[.programlisting] .... -# bectl create 14.2-RELEASE-p4 +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; +} .... -Use this boot environment to start the system as it was before the update if something goes wrong. - Save a list of the non-base packages in case they are needed later: [source,shell] @@ -1242,20 +1253,23 @@ 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 and mount the just created boot environment into that folder to enable working with pkg chroot 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] ==== @@ -1263,6 +1277,85 @@ Be careful. ==== +[WARNING] +==== +According to the mailing list, upgrading from 14 to 15 with pkgbase is not officially supported. +At the time of this writing in some edge-cases the major upgrade removes pkg and therefore segfaults. +This is considered a (link:https://lists.freebsd.org/archives/freebsd-pkgbase/2025-October/001087.html[known issue]) for 15.0-RELEASE. +To work around this issue lock pkg before upgrading. + +[source,shell] +.... +# pkg -c /mnt/upgrade lock pkg +.... +==== + +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 boot environment fails to start, simply reboot and the system will boot back into the previously used boot environment. + +[source,shell] +.... +# bectl activate -t 15.0-RELEASE +shutdown -r now +.... + +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 +[WARNING] +==== +According to the mailing list, upgrading from 14 to 15 with pkgbase is not officially supported. +At the time of this writing in some edge-cases the major upgrade removes pkg and therefore segfaults. +This is considered a (link:https://lists.freebsd.org/archives/freebsd-pkgbase/2025-October/001087.html[known issue]) for 15.0-RELEASE. +To work around this issue lock pkg before upgrading. + +[source,shell] +.... +# pkg lock pkg +.... +==== + 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 +1376,26 @@ 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 update +# 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 network