FreeBSD 12.2, UEFI, Zpool Upgrade and Updating Disk Boot Code

Recently, an upgrade from FreeBSD 12.1 to FreeBSD 12.2 led me down a path to examine the process of updating the boot code on the boot disk. After reading several forum and email list posts about this issue, I decided to create a VirtualBox VM to test solutions before upgrading the zpool and disk boot code on my ThinkPad.

The process of upgrading my ThinkPad Laptop from FreeBSD 12.1 to FreeBSD 12.2 was uneventful. Everything went as planned it rebooted just fine. The only thing needed was to build graphics/drm-fbsd12.0-kmod package from Ports once the system was updated. This was due to the fact that no 12.2 packages exist for the graphics drivers and, therefore, needed to be build via Ports….

After upgrading to FreeBSD 12.2, zpool status command indicated new feature flags available. After upgrading the pool, the boot code for the boot disk requires updating as well. Before attempting this on a production system, I decided to create a virtual machine in order to test the process myself!

Setup:

My setup included both a EFI Partition and a traditional BIOS Boot Partition. This was chosen when installing FreeBSD 12.0 with root on ZFS. Here’s the disk layout:

root@fisher:~ % gpart show
=>        40  2000409184  nvd0  GPT  (954G)
          40      409600     1  efi  (200M)
      409640        1024     2  freebsd-boot  (512K)
      410664         984        - free -  (492K)
      411648    67108864     3  freebsd-swap  (32G)
    67520512  1932888064     4  freebsd-zfs  (922G)
  2000408576         648        - free -  (324K)

zpool upgrade:

root@fisher: # zpool upgrade -a
This system supports ZFS pool feature flags.

Enabled the following features on 'zroot':
  allocation_classes

If you boot from pool 'zroot', don't forget to update boot code.
Assuming you use GPT partitioning and da0 is your boot disk
the following command will do it:

        gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 1 da0

What to do now?

If you issue the above command as with the disk setup above, it will overwrite the EFI Partition with boot code for a traditional BIOS boot setup! The result will a non bootable machine.

To upgrade the Traditional Boot Partition:

root@fisher: # gpart bootcode -b /boot/pmbr -p /boot/gptzfsboot -i 2 nvd0

* Note:  The index (i) is set to 2 to reflect the second slice of the disk - nvd0p2

To upgrade the EFI Partition:

root@fisher: # mount -t msdosfs /dev/nvd0p1 /mnt
             # cp /boot/loader.efi /mnt/efi/boot/BOOTx64.efi
             # umount /mnt

* Note:  The EFI Partition - nvd0p1 is mounted to /mnt in order to modify the contents of BOOTx64.efi
         This is the procedure to utilize for FreeBSD 12.x installations.
         Please see:  https://wiki.freebsd.org/UEFI

Summary:

Since my ThinkPad exclusively boots utilizing UEFI, only the EFI Partition required updating. However, upgrading the boot code for the freebsd-boot partition could be useful as well in the future.

Before updating your boot code whether using UEFI or BIOS booting, please try first in a virtual machine to test your setup. Scouring the FreeBSD email list seems to uncover much discussion but with little consensus on how to provide a path forward to update the boot code after a zpool upgrade. To make matters worse it seems the documentation in the Handbook is not complete with regards to this subject.