Use BEs (ZFS Boot Environments) to manage upgrading with freebsd-update.

Base Upgrade

Create BE for the Upgrade

Be sure to create and activate a new BE when it is time to do a major upgrade of the base system. For example, to upgrade from 12.1-RELEASE to 12.2-RELEASE ...

# uname -a
(verify your current version)
# bectl list
(verify your active BE is named 'default')
# bectl create backup-of-default
# bectl list
(verify the new BE is there)

The new BE named 'backup-of-default' is your backup.

Do the Upgrade

(log back in as root)
# freebsd-update -r 12.2-RELEASE upgrade
# freebsd-update install
# reboot

It is generally a good idea to also upgrade your packages following a kernel upgrade. Let's do that too.

# pkg upgrade
# reboot

Test Drive

Log in. Try a few things. Kick the tires. Take your time to verify all is well.

Clean Up

Once you are comfortable with the upgrade, you can delete the backup BE. The backup BE takes up space that can grow over time as the 'default' BE diverges.

(login as root)
# bectl list
(verify spelling of the BE to be destroyed)
# bectl destroy -o backup-of-default


Suppose things didn't go well after the reboot. You're pressed for time so you decide to delay the upgrade so you can take time to study the problem. No worries. You can rollback.

If you can log in as root:

# bectl activate backup-of-12.1-RELEASE
# reboot

An even easier way is to use the FreeBSD boot loader, choose option 7. On the next screen, tap '2' to cycle through the list of BEs. Pick the 'backup-of-12.1-RELEASE' BE. Tap '1' to go back to the main menu and tap '1' to continue booting.


Now you are back to where you left off before attempting the upgrade. Log back in as root to clean up the broken BE. You're going to destroy (delete) the old 'default' and rename the 'backup-of-default' BE to the name 'default'.

# bectl list
(verify the exact spellings of the BEs)
# bectl destroy -o default
# bectl rename backup-default default
# beclt list
(re-verify the exact spellings of the BEs)

A few weeks later, you read that a patch has been released that may solve your problem. You decide to try again. Go back to the beginning of this page and start over. Good luck.

See Also


unitrunker/base-upgrade (last edited 2020-08-18T04:09:12+0000 by unitrunker)