doc(ZFS): update UEFI loader instructions for 13+

[msimerson]

FreeBSD 13.0+ no longer have boot1.efifat, so replace those instructions with the relevant commands and add reference to loader.efi man page.

[bsdimp]

This looks good to me.

[jrtc27]

By default this will automatically be mounted (bsdinstall puts it in fstab) and so will fail with mount_msdosfs: /dev/ada1p1: Device busy. If you need to mount it manually for whatever reason, mount -t msdosfs is better than mount_msdosfs (which is a bit of an implementation detail).

[msimerson]

Correction, it "may fail." You're assuming the disks were created with bsdinstall. There are more than a few FreeBSD disks roaming about that were installed with sysinstall or were manually partitioned to match disks installed long ago.

[jrtc27]

I realise. I deliberately said by default at the start of the sentence to fully acknowledge there are other ways to get a working FreeBSD system. That is, by default it will fail. That doesn't mean it will always fail.

[msimerson]

How about this?

mount -t msdosfs -u /dev/ada1p1 /boot/efi

[jrtc27]

This assumes amd64

[msimerson]

Fair point. Most of the other FreeBSD docs I've seen only copy loader.efi to bootx64.efi, as that's correct likely ~99% of the time. The wiki page and man page note there is no 32-bit UEFI support.

The two options 'x64' and 'aa64' would cover probably 99.9% of cases.

# cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi
or
# cp /boot/loader.efi /boot/efi/efi/boot/bootaa64.efi

To cover all cases, perhaps borrow from the convention used in the loader.efi man page?

# cp /boot/loader.efi /boot/efi/efi/boot/bootXXX.efi (see uefi(8) for values to replace ‘XXX’ with)

I don't have enough knowledge to explain why we don't just direct users to only copy it to the designated FreeBSD spot:

# cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi

[jrtc27]

This needs to follow the same approach as loader.efi(8). Both locations are important, but which is more important depends on your system. Only updating the removable media path would be wrong for most desktop and server systems. Only updating the FreeBSD-specific path would be wrong for most SBC systems.

[sergio-carlavilla]

Any news with this patch?
@jrtc27 @msimerson

[msimerson]

The current instructions are still completely broken for supported versions of FreeBSD.

This patch makes them much less broken, but only for the vast majority of FreeBSD users. My interest in improving the docs has been exhausted by perfect standing in the way of better.

[jrtc27]

The current instructions are still completely broken for supported versions of FreeBSD.

This patch makes them much less broken, but only for the vast majority of FreeBSD users. My interest in improving the docs has been exhausted by perfect standing in the way of better.

No. The instructions you have provided do not work for the vast majority of FreeBSD users, because they only update the removable media path, which is not what a normal desktop/server installed via bsdinstall will be using.

[grahamperrin]

Open bugs reports include:

• 255318 – handbook: Document how to update the bootloader
• 263322 – Explain when and why to upgrade the bootloader

#408 (comment)

… My interest in improving the docs has been exhausted …

@msimerson if it helps you to feel better about the difficulties with documenting things such as this: for a (very) long time, I did things wrong because my brain switched off after efibootmgr -v in 2023 produced nothing like what's shown under https://www.freebsd.org/releases/14.0R/relnotes/#upgrade.

My own routine includes this, whilst an upgraded but not yet active boot environment is mounted at /tmp/up:

cp /tmp/up/boot/loader.efi /boot/efi/efi/freebsd/loader.efi && cp /tmp/up/boot/loader.efi /boot/efi/efi/boot/bootx64.efi

[msimerson]

I do a similar thing, but I always add /etc/fstab entries with noauto for every one of the disks that has boot loaders. Eg:

➜ grep efi /etc/fstab
/dev/gpt/nda0-efi	/boot/efi	msdosfs	rw,noauto	2	2
/dev/gpt/nda1-efi	/boot/efi	msdosfs	rw,noauto	2	2

I mostly run FreeBSD on servers with mirrored boot disks and those fstab entries are my reminder to update the boot loader on both disks. They also make this little saved snippet work:

df /boot/efi | grep /boot/efi && umount /boot/efi
for _fs in $(grep efi /etc/fstab | awk '{ print $1 }'); do
	mount -t msdosfs -o longnames $_fs /boot/efi
	cp /boot/loader.efi /boot/efi/efi/boot/boot*.efi
	cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi
	umount /boot/efi
done