FreeBSD efibootmgr Operations: Inspect and Repair UEFI Boot Entries Safely

FreeBSD’s efibootmgr(8) reads and changes UEFI boot variables stored by platform firmware. It is a small tool with machine-wide effects: a boot entry can be disabled, deleted, moved to the front of BootOrder, or selected for only the next reboot. A typo in an EFI path or an incorrect assumption about the EFI System Partition can turn a running server into a remote-console recovery problem.

Treat firmware configuration separately from the disk layout and from FreeBSD’s loader configuration. efibootmgr edits NVRAM variables; gpart describes partitions; files such as /boot/loader.conf configure the loader after firmware has found it. Changing one layer does not repair the others. Begin with read-only inventory and preserve a known-good fallback before writing anything.

Establish that the machine booted through UEFI

Check the running kernel’s environment and inspect the partition table before interpreting firmware entries:

sysctl machdep.bootmethod
gpart show -lp
mount -p

The exact machdep.bootmethod output depends on the release and machine. If the system booted through legacy BIOS, a missing or irrelevant EFI entry is not evidence that the FreeBSD installation is broken. gpart show -lp helps identify an EFI System Partition, while mount -p shows whether it is mounted. Neither command proves the firmware can read a particular loader file.

For FreeBSD 15.1, the upgrade instructions use machdep.bootmethod on AMD64 to select the boot-loader procedure and state that AArch64 systems always use UEFI. Do not interpret an unavailable architecture-specific sysctl as proof that a UEFI installation is broken; verify the architecture and consult its release-specific boot documentation.

On a UEFI installation, locate the EFI partition and inspect its contents read-only. If it is not mounted, identify its provider from the partition table and mount it at a temporary directory using the FAT filesystem driver appropriate to that partition. Do not guess a device name such as ada0p1 on a system that may use NVMe, virtio, or multipath storage. Record the mountpoint and unmount it when finished.

The loader path passed to efibootmgr -l is interpreted by firmware relative to the EFI System Partition, not as a pathname on the mounted FreeBSD root. The FreeBSD manual’s example uses /boot/efi/EFI/freebsd/loader.efi for a partition mounted at /boot/efi; another installation may use a different directory or loader filename. Confirm the file exists on the actual EFI partition before creating an entry.

Capture the firmware’s current state

Start with the verbose listing and preserve it with the maintenance record:

efibootmgr -v

Record the Boot#### identifiers, active markers, device paths, labels, BootOrder, and BootNext where present. A human-readable label is not a trustworthy identity by itself: two entries can both say FreeBSD while pointing to different disks or loader files. The verbose device path is the clue that distinguishes them.

Do not treat the displayed order as proof of successful boot. Firmware can ignore an entry whose device path no longer resolves, and some implementations apply their own boot policy. If the system was installed on a cloned or replaced disk, a valid-looking old entry may still refer to the former EFI partition. Cross-check the partition GUIDs and physical disk inventory against the machine’s current topology.

Keep a copy of the listing outside the host as well as in the change ticket. If remote access is lost after reboot, that record can tell an operator which entry and order to restore from a console. Do not capture only the output of efibootmgr -v after a change; retain the before-state too.

Create one entry only after validating the EFI file

The FreeBSD manual illustrates creating an active entry with a label and a path on the mounted EFI System Partition. Adapt its command only after confirming the mountpoint and loader path:

efibootmgr -a -c -l /boot/efi/EFI/freebsd/loader.efi -L FreeBSD-15
efibootmgr -v

The -c option creates an entry; -a marks it active. The manual documents newly created entries as inactive by default unless activated. It also notes that a created entry can be inserted at the first position in an existing BootOrder. That makes the command more than a harmless label operation: it can change what the next ordinary reboot tries first.

Compare the new entry’s device path with the actual EFI partition and verify the label and active state. Then inspect BootOrder again. If the new entry was inserted ahead of an existing recovery or vendor entry, decide deliberately whether that is the desired result. Do not make several speculative entries with different path spellings; duplicates make future incidents harder to diagnose.

If the firmware cannot access a mounted path, stop rather than changing the root filesystem. Check the EFI partition’s filesystem, the loader file’s exact case and directory, the partition’s GPT type, and the firmware’s device path. On systems with removable-media fallback behavior, test the documented fallback layout separately; do not assume every firmware searches it in the same way.

Change order and one-shot boot separately

BootOrder controls the ordered list the firmware normally considers. BootNext selects a one-time entry for the next boot attempt. The manual documents separate operations:

# Schedule one controlled test boot by the recorded boot number.
efibootmgr -n -b 0009

# Set an explicit persistent order after confirming every listed number.
efibootmgr -o 0009,0003,0001

# Re-read the state before leaving the console.
efibootmgr -v

Replace these illustrative numbers with the identifiers returned on this machine. Do not copy them literally. A one-shot selection is often preferable during recovery because it can test a candidate without permanently rewriting the sequence, but firmware behavior and fallback policy still matter. If the candidate fails, the next boot’s state may differ from the operator’s expectation; verify from a console rather than assuming rollback occurred.

Schedule a reboot only when out-of-band access or an on-site recovery path is available. A running kernel cannot prove that the new entry will be honored after the current session ends. In virtual machines, inspect the hypervisor’s configured firmware and boot devices too; guest NVRAM persistence and device ordering are controlled partly outside FreeBSD.

Disable or delete with a rollback plan

The tool can mark an entry inactive or delete it by number. Inactivation is easier to reverse than deletion and is preferable while diagnosing an uncertain entry. Before removing anything, verify that another tested FreeBSD path and any required vendor recovery path remain available. Deleting a number selected from stale notes can remove the wrong entry because firmware identifiers are not universal across hosts.

After a change, list variables again and compare the complete state, not merely the line edited. Confirm the expected active marker, BootOrder, and BootNext. If an entry must be removed, capture its verbose device path and number before removal and preserve that data until a successful boot has been observed.

NVRAM capacity is finite. Repeatedly creating test entries can consume space or make firmware menus confusing. Prefer editing or deleting a verified duplicate after recording it, and avoid automated scripts that create entries on every boot. A failed variable write can indicate firmware limitations or storage exhaustion; it is not a reason to delete unknown entries blindly.

Verify the complete boot chain

Successful entry creation verifies only that a variable was written. A complete test checks several distinct transitions: firmware selects the intended entry, reads the intended EFI System Partition, starts loader.efi, loads the kernel and root filesystem, and reaches the expected multi-user state. Capture console output when testing a new path and compare the running root device and release afterward.

If the firmware menu shows the entry but boot fails, return to the before-state rather than making additional changes under pressure. A missing file, stale disk GUID, unsupported firmware path, or loader problem requires a different repair from a malformed BootOrder. Keep the working fallback until the candidate has passed at least one controlled reboot and the expected operating environment has been confirmed.

efibootmgr is a firmware-variable editor, not a bootloader repair wizard. Small, recorded changes with console access are safer than broad resets. The operational success criterion is not “the command returned zero”; it is “the intended path completed a verified boot and the fallback remains recoverable.”

Related:

Sources: