doc(ZFS): update UEFI loader instructions for 13+ by msimerson · Pull Request #408 · freebsd/freebsd-doc

msimerson · 2024-08-27T22:15:35Z

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.

documentation/content/en/books/handbook/zfs/_index.adoc

jrtc27 · 2024-09-03T15:25:14Z

documentation/content/en/books/handbook/zfs/_index.adoc

 ....
-# gpart bootcode -p /boot/boot1.efifat -i 1 ada1
+# mount_msdosfs /dev/ada1p1 /boot/efi
+# cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi


This assumes amd64

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

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 · 2025-01-18T09:57:27Z

Any news with this patch?
@jrtc27 @msimerson

msimerson · 2025-01-19T18:27:28Z

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 · 2025-01-19T18:46:23Z

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 · 2025-03-19T03:14:56Z

Open bugs reports include:

#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

Postscript

16.0-CURRENT on ARM64 in QEMU

root@freebsd:/tmp # efibootmgr -v

Boot to FW : false
BootCurrent: 0001
Timeout    : 5 seconds
BootOrder  : 0001, 0000
+Boot0001* UEFI Misc Device PciRoot(0x0)/Pci(0x1,0x4)/Pci(0x0,0x0)
 Boot0000* UiApp Fv(64074afe-340a-4be6-94ba-91b5b4d0f71e)/FvFile(462caa21-7614-4503-836e-8ab6f4662331)


Unreferenced Variables:
root@freebsd:/tmp # freebsd-version -kru ; uname -mvKU

16.0-CURRENT
16.0-CURRENT
16.0-CURRENT
FreeBSD 16.0-CURRENT main-n284556-ba4298b05564 GENERIC arm64 1600013 1600013
root@freebsd:/tmp # mount | grep efi

/dev/gpt/efiboot0 on /boot/efi (msdosfs, local)
root@freebsd:/tmp # `

Only one occurrence of efibootmgr -v in the doc tree:

grahamperrin@mowa219-gjp4 ~/d/f/doc (main)> rg -il 'efibootmgr -v'  . --sort=path
./website/content/en/releases/14.0R/relnotes.adoc
grahamperrin@mowa219-gjp4 ~/d/f/doc (main)> `
``

msimerson · 2025-03-20T02:45:28Z

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

more robust instructions

documentation/content/en/books/handbook/zfs/_index.adoc

grahamperrin · 2026-03-19T01:30:19Z

Cross-reference:

293912 – FreeBSD Handbook: ZFS: wrong gpart instruction

Postscript, for anyone who's not already aware:

bsdimp · 2026-03-19T16:26:24Z

documentation/content/en/books/handbook/zfs/_index.adoc

-# gpart bootcode -p /boot/boot1.efi -i 1 ada1
+# umount /boot/efi
+# mount -t msdosfs /dev/ada0p1 /boot/efi
+# cp /boot/loader.efi /boot/efi/efi/boot/boot*.efi


The '*' here doesn't make sense.
It should be to bootx64.efi.
With a note somewhere saying that's architecture dependent (but ada is primarily a x86 thing) and please refer to this table for the name of other ports. I think that table is in loader.efi, in the examples.

My newer devices present at ndaN because they're NVMe. Disks attached via SAS/SCSI (the CAM layer) present as daN. Disks attached via (S)ATA present at adaN. Some RAID controllers present differently. There's no universal command that'll work there, so perhaps it needs to be:

export BOOT_DEVICE="/dev/{daN | ndaN | adaN}" # CUSTOMIZE THIS! mount -t msdosfs "$BOOT_DEVICE" /boot/efi

The copy command with the * works across TIER 1 (and probably all other) supported architectures:

# ls /boot/efi/efi/boot/boot*.efi /boot/efi/efi/boot/bootaa64.efi # uname -p = aarch64 /boot/efi/efi/boot/bootx64.efi # uname -p = amd64

If there was a reasonable chance of it getting merged, I'd update this PR with this:

# Common EFI: /dev/nda0 (NVMe), /dev/ada0 (SATA), /dev/da0 (USB/SAS/SCSI) # Note: For mirrored boot drives, update BOTH disks. # export EFI_PARTITION="/dev/{ndaN | daN | adaN}" # CUSTOMIZE THIS! # mount | grep -q /boot/efi && umount /boot/efi # mount -t msdosfs "$EFI_PARTITION" /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

This is more robust, and compared the more static commands above:

installs when no boot loader exists

works with all EFI platforms.

ARCH matches the two exceptions to the boot{ARCH}.efi naming convention.

other architectures (arm) work by default

doesn't require users to figure out partition names

improves on my in-house script that relied on an up-to-date /etc/fstab

EFI requires gpart partitions

# discover the EFI name for this systems CPU architecture export ARCH=$(case "$(uname -p)" in aarch64) echo "aa64" ;; amd64) echo "x64" ;; *) echo "$(uname -p)" ;; esac) for _efi_part in $(gpart show -p | grep ' efi ' | awk '{ print $3 }') do echo; echo " updating $ARCH EFI boot loader in $_efi_part" mount | grep -q 'on /boot/efi ' && umount /boot/efi mount -t msdosfs "/dev/$_efi_part" /boot/efi mkdir -p /boot/efi/efi/boot /boot/efi/efi/freebsd cp /boot/loader.efi "/boot/efi/efi/boot/boot${ARCH}.efi" cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi umount /boot/efi done

Sample Output

amd64 (Intel)

updating x64 EFI boot loader in mmcsd0p1 mount | grep -q /boot/efi && umount /boot/efi mount -t msdosfs /dev/mmcsd0p1 /boot/efi cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi umount /boot/efi updating x64 EFI boot loader in nda0p1 mount | grep -q /boot/efi && umount /boot/efi mount -t msdosfs /dev/nda0p1 /boot/efi cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi umount /boot/efi updating x64 EFI boot loader in nda1p1 mount | grep -q /boot/efi && umount /boot/efi mount -t msdosfs /dev/nda1p1 /boot/efi cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi umount /boot/efi updating x64 EFI boot loader in nda2p1 mount | grep -q /boot/efi && umount /boot/efi mount -t msdosfs /dev/nda2p1 /boot/efi cp /boot/loader.efi /boot/efi/efi/boot/bootx64.efi cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi umount /boot/efi

ARM 64

updating aa64 EFI boot loader in nda0p1 mount | grep -q /boot/efi && umount /boot/efi mount -t msdosfs /dev/nda0p1 /boot/efi cp /boot/loader.efi /boot/efi/efi/boot/bootaa64.efi cp /boot/loader.efi /boot/efi/efi/freebsd/loader.efi umount /boot/efi

Update _index.adoc

ec4d182

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 approved these changes Aug 31, 2024

View reviewed changes

jrtc27 reviewed Sep 3, 2024

View reviewed changes

msimerson closed this Jan 20, 2025

msimerson reopened this Mar 20, 2025

Update _index.adoc

83027d7

more robust instructions

grahamperrin reviewed Mar 22, 2025

View reviewed changes

documentation/content/en/books/handbook/zfs/_index.adoc Outdated Show resolved Hide resolved

rename ada1 -> ada0 in example

34b76ba

concussious added the needs-review label Dec 4, 2025

concussious requested review from bsdimp and jrtc27 December 4, 2025 04:22

Merge branch 'main' into patch-1

79d71bf

bsdimp reviewed Mar 19, 2026

View reviewed changes

Conversation

msimerson commented Aug 27, 2024

Uh oh!

bsdimp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jrtc27 Sep 3, 2024

Choose a reason for hiding this comment

Uh oh!

msimerson Sep 3, 2024 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jrtc27 Jan 18, 2025

Choose a reason for hiding this comment

Uh oh!

sergio-carlavilla commented Jan 18, 2025

Uh oh!

msimerson commented Jan 19, 2025

Uh oh!

jrtc27 commented Jan 19, 2025

Uh oh!

grahamperrin commented Mar 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Postscript

Uh oh!

msimerson commented Mar 20, 2025

Uh oh!

Uh oh!

grahamperrin commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

bsdimp Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msimerson Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

msimerson Mar 19, 2026

Choose a reason for hiding this comment

Uh oh!

msimerson Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Sample Output

amd64 (Intel)

ARM 64

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

msimerson Sep 3, 2024 •

edited

Loading

grahamperrin commented Mar 19, 2025 •

edited

Loading

grahamperrin commented Mar 19, 2026 •

edited

Loading

bsdimp Mar 19, 2026 •

edited

Loading

msimerson Mar 19, 2026 •

edited

Loading

msimerson Mar 19, 2026 •

edited

Loading