Upgrading to FreeBSD 13.0-RELEASE

Recently the FreeBSD project announced the official release of FreeBSD 13.0-RELEASE which I found very exciting given my recent experience with it on the Desktop. Upgrading a full OS has always made me a little anxious as to what could/would break, so as excited it made me, I was also a little aprehensive to try it out.

Luckily, I had a few "tools" available to soften up the process, and great documentation on FreeBSD's part again provided a lot of good information, and I can say the transition went smoothly. Perhaps I could say that it's as easy as upgrading a Debian install, perhaps even easier, but it does take some time, perhaps more than some Linux Distros. This post outlines how the process goes and my experience with trying it cold turkey.

Let's go!

Which release do you choose?

One of the things that stand out from FreeBSD's release system is its rather unique release naming method: besides the version number (13.0 being the most recent as of this writing), you must choose between three branches of STABLE, RELEASE and CURRENT.

This was something that confused me a little initially as well, but upon some searching (I believe this is somewhere in the Handbook as well), it's actually similar to the way Debian does its releases. Without going into too much technical detail, these are the main difference between the three:

RELEASE is the extensively-tested, super-stable release of FreeBSD. Updates are rare, usually reserved to Security patches and crucial stuff, but is the most stable release of all the software. It's sort of analogous to Debian Stable, and I hear it's the version recommended for servers.
STABLE is the fresh, tested version of FreeBSD, which although less tested than STABLE, software here gets updated more frequently, and is a step closer to more up to date stuff, suitable for daily use as your desktop OS or server alike.
CURRENT is analogous to Debian Sid (Unstable): the "cutting edge" of software in the FreeBSD world. It receives some testing, but its focus is the latest releases of software in FreeBSD. I've never used it, but read elsewhere that this version is more tested than Debian Sid, and can be used as a main OS if caveats are accepted.

The Handbook, as usual has a very detailed explanation concerning the Development Branches of FreeBSD

Procedure overview

The FreeBSD project has created a tool called freebsd-update which greatly simplifies the entire upgrading process, especially if you only use the pkg tool to manage binary packages for additional software. There are also source-based upgrades but as I never use the ports software save for very specific exceptions, I didn't explore that path.

Using this method, the upgrading process becomes very simple, and actually resembles the way that Debian is upgraded between two Stable releases. The macroprocess is as follows:

Point the freebsd-update tool to the new release and populate it with updates.
Install the updates to the system base.
Reboot to update the base system.
Update the rest of the system.

The total time taken for me was about 20min, not counting the reboot and command-entering, but the system was also fairly simple, so it might vary.

Let's see each step of the process.

Warning: make sure you have enough disk space!

Probably a no-brainer for most people, but make sure you have a few Gigabytes of space available on your system before attempting to upgrade. This is because the freebsd-update tool will store the updates in cache before performing the update, and these can get significantly large, the equivalent of downloading a new FreeBSD ISO off the internet.

Chances are your computer will have plenty of space to acommodate for this, but when I first tried this on a VM, the space I reserved for it to begin with was too small to house these updates, but FreeBSD did not warn me of it. As a result, the upgrading process clogged right after the fetching of files (disk usage went up to 106%, go figure), and the system became unusable.

Lesson learned the hard way: make sure you have more than just a few GB left of Disk space before running the update.

Run the show

Got enough space and an internet connection? Good. Let's get going:

Prepare the system

In general, to avoid conflicts and things breaking unrecoverably from one update to another, I tend to bring the system down to the bare minimum: the console session.

I recommend a full reboot to clean up any other unnecessary process and start afresh, but if you'd rather not, quit your window manager and drop down to the shell, and make sure there are no other sessions running on the other TTYs. Now that you're down to the barebones of the system, it's time to get busy.

Update the base

freebsd-update -r <release version> install

Since I'm updating from 12.2-RELEASE to 13.0-RELEASE, my command is:

freebsd-update -r 13.0-RELEASE install

freebsd-update fetches the release files and caches them locally. Upon all fetching, the installation begins with each updated package of the base system replacing the older version. Should any discrepancy arise between the local configuration files and the updated ones, the script will warn you of so.

This is the step that takes the most time due to the download size, but you'll see a progress counting how many packages have been downloaded as sort of a way to know how long you have left. After the system base has been updated, you'll be prompted to reboot.

Update the rest of the system

Once you reboot, you're actually only halfway done: there's still the need to update the rest of the system. Turns out that the freebsd-update tool still keeps cached some packages locally that must be installed upon the reboot, so this is the time for it:

freebsd-update install

The remaining updates will be installed. Finally, for good measure, install the remaining packages normally with pkg:

pkg upgrade

After this, reboot and voila: you're running the most recent version of FreeBSD.

Conclusion

Upgrading FreeBSD to another release is pretty easy when you manage it in a binary package basis. The commands are:

freebsd-update -r 13.0-RELEASE upgrade
reboot
freebsd-update install
pkg upgrade
reboot

And this should be it, at least here I had no issues so far. If you're using a source-based installation or ports, however, I'm not sure how the upgrade goes. Some comments on IRC spoke of taking hours or even days to complete, or people upgrading their "repository servers" first before upgrading their main machines. Perhaps that should be something I must revisit on my next upgrade. In the meantime, source updating is also covered in the Handbook for everyone that's interested.

Have you recently upgraded to FreeBSD 13.0-RELEASE? How did the process go? Let me know on Mastodon!

UPDATE: whoops! Seems that I confused the meaning of STABLE and RELEASE, it's actually the other way around. STABLE is akin to Debian Testing, not quite bleeding edge but still being tested. When all testing is clear, things move to be RELEASEd. Thanks to 0mp for posting that out.

This post is number #14 of my #100DaysToOffload project. Follow my progress through Mastodon!

Last updated on 04/23/21