Boot Environments Make for Safe and Convenient Upgrades

Published: 3 Mar, 2019

Use ZFS Boot Environments to safely perform system upgrades

What are Boot Environments

In a nutshell, boot environments are ZFS filesystems that are marked bootable. The idea is that you can have multiple boot environments and boot into one that you like by setting it as active.

Specifically, a bootable filesystem is set with a bootfs property on a boot pool. E.g. our system has a ZFS pool called bootpool and we can see what the current bootable filesystem is by looking at the bootfs property:

sudo zpool get bootfs bootpool
NAME      PROPERTY  VALUE                  SOURCE
bootpool  bootfs    bootpool/ROOT/default  local

I can create a new filesystem and update the bootfs property on the pool to boot from it, all with the standard ZFS tools. beadm tool however makes managing boot environments a tad simpler.

On the same server, here are the boot environments present:

sudo beadm list
BE              Active Mountpoint                  Space Created
default         NR     /                            8.5G 2018-11-06 12:48

default is the special name for the initial BE on the system.

How to perform a system upgrade by relying on boot environments

beadm(1) man page includes an example on how to perform an upgrade in a jail(8), but jail is an unnecessary overhead, we can perform a safe upgrade without using jails at all.

Lets go over the steps.

First, create a new BE as a clone from your live BE, which is default in our case. We’re going to call the new BE 12.0-RELEASE-p3 as that’s the version we’re upgrading to.
```
sudo beadm create -e default 12.0-RELEASE-p3
```

Checkout the new BE under the hood

sudo beadm list -aD
BE/Dataset/Snapshot                 Active Mountpoint                  Space Created

default
bootpool/ROOT/default             NR     /                            5.3G 2018-11-06 12:48

12.0-RELEASE-p3
bootpool/ROOT/12.0-RELEASE-p3     -      -                            3.3M 2019-03-03 12:55
default@2019-03-03-12:55:02     -      -                            5.0G 2019-03-03 12:55

Now lets mount the new BE somewhere obvious, so we can perform an upgrade on it in isolation. The mountpoint directory will be created automatically if it doesn’t exist:
```
sudo beadm mount 12.0-RELEASE-p3 /jails/kronos-12.0-release
```
Next, upgrade the new BE. Here, instead of using a jail as per beadm(1) man page, we make use of the basedir option in freebsd-update(1) to point it to the directory containing the filesystem to upgrade. Other than that, we’re following the standard freebsd-update(1) process here, with the only difference being that we’re upgrading a standalone filesystem and therefore don’t need to reboot. In other words, the steps can be executed one after another:
```
sudo freebsd-update -r 12.0-RELEASE -b /jails/kronos-12.0-release upgrade
sudo freebsd-update -r 12.0-RELEASE -b /jails/kronos-12.0-release install
sudo freebsd-update -r 12.0-RELEASE -b /jails/kronos-12.0-release install
sudo pkg -c /jails/kronos-12.0-release upgrade -fy
sudo freebsd-update -r 12.0-RELEASE -b /jails/kronos-12.0-release install
```

Note that we need to reinstall all packages since this is a major version upgrade. You don’t not need this step for minor version upgrades, do what freebsd-update(1) tells you to do and you should be fine.

Now our new BE is upgraded and ready. We mark it as active and reboot when convenient.
```
sudo beadm activate 12.0-RELEASE-p3
```

We can verify which BE will be booted next, its identified by letter R (i.e. active on Reboot):

sudo beadm list
BE              Active Mountpoint  Space Created
default         N      /mnt        29.6M 2018-11-06 12:48
12.0-RELEASE-p3 R      /           10.2G 2019-03-04 06:09

And reboot at your convenience

If things are looking poorly after the reboot, reverting back to your previous BE is as easy as sudo beadm activate default followed by another reboot.

Hope this helps and reduces the risk with your next upgrade.