How to use the FreeBSD update utility to safely upgrade the FreeBSD base system to newer minor and major releases of FreeBSD. And rollback.
New release announcements.
New versions of FreeBSD are posted on the front of the homepage.
The supported releases comes with an announcement, release notes, installation instructions, hardware compatibility list, readme, errata and more, which you might want to look into before upgrading.
https://www.freebsd.org/releases
Determine the version of FreeBSD kernel and userland.
The built-in freebsd-version utility can determine the installed, running and userland version and patch level of FreeBSD. These should all match, but it is not uncommon, that userland is different.
# freebsd-version -k -r -u
Confirm, that the system can be restored in case of failure.
You might want to ensure, that the system can be restored, if something goes wrong during the upgrade.
If the FreeBSD in question runs on a virtual host, then an offline snapshot at this point in time will make you able to do a quick and easy restore. If the system uses ZFS, then a snapshot can also be used to do a quick restore of one or more datasets. This requires, that the file system and partitions are still working.
You might also want to ensure, that you have a backup of your current working kernel. In case of boot problem, you will be able to select your working kernel from the FreeBSD boot menu. FreeBSD stores an older version of the current kernel in kernel.old, which can also be selected from the FreeBSD boot menu.
# cd /boot # cp -r kernel `date -I`-kernel
In any case you should be able to restore the data from a regular backup repository.
Make sure, that FreeBSD can reboot.
If you have custom kernel settings, you might want to return some of those to default settings, so you are sure, that you can reboot and read the terminal output, if the upgrade proces makes changes to kernel settings. An example is the default resolution, that you might want to comment out.
# nano /boot/loader.conf #kern.vt.fb.default_mode="960x540"
Upgrade FreeBSD to new minor or major version.
FreeBSD can be upgraded to a new minor or major release by using the built-in freebsd-update utility, which can fetch, install and rollback binary updates to the FreeBSD base system. The current patch level does not matter. The upgraded system will have the current patch level.
The update utility will first inspect the system before it will fetch patches, apply patches, fetch files and merges changes in configuration files. The patches and files depends on the internet speed and can take a long time. If you will be upgrading a remote server, you might want to perform the upgrade in a detachable terminal, such as screen, so you can attach the terminal in the case of disconnection.
In the following example FreeBSD is upgraded from 12.1 to 12.2. It is possible to skip minor versions, such as 12.2 to 13.0, where 12.3 is skipped, but I would generally advice against it. I would not advice to skip any major version.
# freebsd-update -r 12.2-RELEASE upgrade
When the first step has completed, then the kernel updates can be installed and the system can be rebooted into the installed kernel.
# freebsd-update install # reboot
The userland updates, which is everything else than the kernel updates, can now be installed. This depends on hardware and can take some time.
# freebsd-update install # reboot
If a third party software rebuild is required.
If the upgrade requires, that old shared object files are removed, then third party software, such as packages and ports, needs to be rebuilt. This rebuild can also be done, if you experience problems with packages after the upgrade.
If packages are used, then a static version of pkg can be used to upgrade itself and packages.
# pkg-static install -f pkg # pkg-static upgrade -f
If ports are used, then portmaster can be used to upgrade the ports, but the recommended practice is, that the package builder poudriere and pkg-static is used. Follow the last procedure, that is given in the manual.
# man portmaster
If a mix is used, then portmaster can be used to rebuild the ports after the packages has been rebuilt. They will overwrite the target files. An example of this could be a desktop computer, which has to use a special port, that replaces a default package, such as a graphics driver.
When third party software has been rebuilt, then the freebsd-update utility can finish the upgrade.
# freebsd-update install # reboot
If the running kernel can not be identified.
If the running kernel can not be identified, then a symbolic link can be created as a work-around and the upgrade can be continued. This is a problem, that is related to encryption and ZFS. The issue is described in FreeBSD Forums.
Cannot identify running kernel # ln -s /bootpool/boot /boot # freebsd-update install
If the upgrade failed and you want to rollback the upgrade.
If the upgrade failed, then the upgrade can be rolled back by using the rollback feature of the freebsd-update utility.
# freebsd-update rollback # reboot
If the upgrade was succesful.
If the upgrade was succesful, then the new version and patch level of FreeBSD can be confirmed with the freebsd-version utility.
# freebsd-version -k -r -u
You should update packages and ports at this point. That is especially important, if you performed a major update. You can read my post about this in How to upgrade and audit packages in FreeBSD. This will ensure, that your FreeBSD system is completely updated.
If you use the Direct Rendering Manager (DRM) kernel module for Intel and AMD chips, then you might have to uninstall the old version and install the new version.
# pkg version | grep drm
If you are using SASL authentication and TLS certificates with Sendmail, then you might have to reconfigure and recompile sendmail.
More about updating FreeBSD.
⧐ How to update (patch) the FreeBSD system.
⧐ How to upgrade and audit packages in FreeBSD.