This is the comprehensive procedure on how to use the FreeBSD update utility to safely upgrade the FreeBSD base system to newer minor and major releases of FreeBSD or roll it back. This page was updated 2024-05-05.
Announcements of new releases of FreeBSD.
New versions of FreeBSD are announced on the front of the official FreeBSD website.
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
Test, that critical applications will work with new release.
If you use virtualization software or critical applications, you might want to consider testing the upgrade of FreeBSD on another computer, before you initiate the upgrade. An alternative to this, can be to wait some time, before you upgrade the FreeBSD base. The reason is, that it can take some time, before virtualization software and crititical applications, or its dependencies, works with the new minor or major release version of FreeBSD.
Delete old FreeBSD system boot environments.
When FreeBSD is upgraded and the downloaded upgrades are about to be installed, then a ZFS snapshot and a clone of the system boot environment is created. This means, that the current system boot environment has been cloned and preserved as a ZFS dataset, while the current is being upgraded. Boot environmens can take up a large amount of space on the file system. This can especially be a problem on virtual private servers, which has limited space. In the following example, the boot environment utility is used to list and delete system boot environments and their ZFS snapshots. The list will sorted by creation date.
You might want to list and delete old boot environments in order of creation, until you are satisfied with the space, that they take up.
# bectl list -c creation # bectl destroy -o 13.2-RELEASE-p10_2024-04-03_111337
You might also write a script to automize this. The benefit of this is, if you have many boot environments, that you want to delete. The following script makes a list of old FreeBSD system boot environments and then deletes them.
#!/usr/local/bin/bash belist="/tmp/boot-environments.txt" bectl list -H -c creation | grep -v "default" | cut -f 1 > "$belist" if [ ! -f "$belist" ]; then echo "File not found." exit 1 fi echo "Listing boot environments, that will be deleted." while read -r be; do echo "$be" done < "$belist" echo "Do you want to continue?" read -s -n 1 answer if [ "$answer" != "Y" ] && [ "$answer" != "y" ]; then echo "Exiting..." exit 0 fi while read -r be; do echo "Deleting boot environment "$be"." sleep 1 bectl destroy -o "$be" || exit 1 done < "$belist" if [ -f "$belist" ]; then rm "$belist" fi
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
Make sure, 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.
Create a backup of the current working kernel in FreeBSD.
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 13.3. 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 13.3-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.