FreeBSD Manual Pages
LOADERUPDATE(8) System Manager's Manual LOADERUPDATE(8) NAME loaderupdate -- update boot loaders SYNOPSIS loaderupdate [-d destdir] [-L efilabel] [-B {ufs, zfs}] [-b bootloader] [-e efiloader] [-o efifile] [-p pmbr] [-cDfnq] device ... loaderupdate [-d destdir] [-L efilabel] [-B {ufs, zfs}] [-b bootloader] [-e efiloader] [-o efifile] [-p pmbr] [-cDfnq] -a loaderupdate [-d destdir] [-L efilabel] [-B {ufs, zfs}] [-b bootloader] [-e efiloader] [-o efifile] [-p pmbr] [-cDfnq] -P [-a | device ...] loaderupdate -h DESCRIPTION The loaderupdate script updates the boot loaders of a given set of bootable devices according to a given boot environment. The boot environment must contain a system kernel under /boot/kernel/kernel as well as the required loader images. The defaults of which can be over- ridden by the -b, -e and -p parameters. Which boot loaders are used by de- fault also depends on the filesystem of the boot environment. The default boot environment / can be overridden by providing the path to the current mountpoint of a different boot environment via the DESTDIR en- vironment variable, or the -d parameter. The "BOOTSTRAPPING" section of gpart(8) provides a good overview of the boot process. By default the loader update is performed if there is a checksum mismatch between the respective loader image and the loader on disk. The -f option can be used to force the loader update. Arguments The following argument types can be given: destdir The path of the mountpoint for the boot environment containing the kernel and boot loader images. The default boot environment is /. efifile Formatting string for the EFI file destination, defaults to: "/efi/{ostype}/boot{arch}.efi" The following substitutions are available: {arch} The kernel architecture {efiarch} The architecture as used by EFI default paths (e.g. X64) {ostype} The OS type (FreeBSD or derived) Supports the formatting style described by bprintf(1). efilabel Formatting string for EFI boot manager entry labels, defaults to: "{version} {arch} [{pdev}]" The following substitutions are available: {dev} The device containing the partition {pdev} The device of the efi partition {index} The index of the efi partition {version} The kernel version {arch} The kernel architecture {efiarch} The architecture as used by EFI default paths (e.g. X64) {ostype} The OS type (FreeBSD or derived) Supports the formatting style described by bprintf(1). bootloader The boot loader image to use for freebsd-boot partitions. The de- fault is either /boot/gptboot or /boot/gptzfsboot, depending on the filesystem containing the boot environment. efiloader The boot loader image to use for EFI partitions, the default is /boot/loader.efi, the EFI variant of loader(8). pmbr The protective MBR image installed in front of the GUID Partition Table. The protective MBR chain-boots the freebsd-boot partition on systems booting in legacy BIOS mode. This is only installed if a freebsd-boot partition is present. The default protective MBR image is /boot/pmbr. device The hard disk device to update. Options The following options are available: -a, --all Selects all available devices. -B {ufs, zfs}, --bootfs {ufs, zfs} Override the boot filesystem detection. Providing -B ufs or -B zfs is equivalent to providing -b /boot/gptboot or -b /boot/gptzfsboot. -b bootloader, --bootloader bootloader Override the default freebsd-boot loader image. -c, --compat Override the EFI loader destination inside the EFI partition with the uefi(8) default location /EFI/BOOT/BOOT{efiarch}.EFI. This provides compatibility with systems that ignore or forget boot entries made with efibootmgr(8), such as virtual machines that do not persist the EFI boot configuration. Warning, not all uefi(8) implementations support these default lo- cations, use -o to supply a proprietary location. -D, --dry-run Instead of updating the boot loaders just show the commands that would be run. In combination with -q this does not print anything apart from errors, which is useful to run all checks performed by loaderupdate without committing any changes. -d destdir, --destdir destdir Override the default boot environment. -e efiloader, --efiloader efiloader Override the default EFI loader image. -f, --force Force update of loaders that are already up to date. -L efilabel, --label efilabel Set a custom label for EFI boot manager entries. -n, --noefi Do not create EFI boot manager entries via the efibootmgr(8) com- mand. This is useful when preparing a disk for another system. -o efifile, --efifile efifile Override the EFI loader destination inside the EFI partition with efifile. This can be used on systems that neither persist the EFI boot con- figuration nor support the uefi(8) default locations available via -c. -P, --dump Instead of performing boot loader updates print a summary of the boot environment and selected devices. -p pmbr, --pmbr pmbr Override the default protective MBR image. -q, --quiet Do not print the commands that are run. This flag does not suppress the output from those commands. ENVIRONMENT DESTDIR Overrides the default boot environment. FILES /boot/kernel/kernel Used to determine the version, architecture and OS to boot by ex- tracting the version, machine and ostype symbols from the kernel binary. /boot/gptboot The freebsd-boot partition image for booting from UFS, see gpt- boot(8). /boot/gptzfsboot The freebsd-boot partition image for booting from ZFS, see gpt- boot(8). /boot/loader.efi The default EFI variant of loader(8). Capable of booting from UFS and ZFS, alternatives include /boot/loader_4th.efi, /boot/loader_lua.efi and /boot/loader_simp.efi. /boot/pmbr The default protective MBR image. /usr/include/sys/disk/mbr.h Required to locate the protective MBR inside a block device for checksum verification. EXIT STATUS The following is a list of all anticipated exit codes: EOK=0 Command completed successfully. ESIGNAL=1 Interrupted by signal. EFAIL=2 Generic application logic error. EPARAM=3 Invalid or conflicting arguments were supplied. ENODEVICE=4 No or inaccessible devices selected. EDESTDIR=5 The destdir is not a directory. ENOKERNEL=6 Cannot access kernel in destdir. EEFILABEL=7 Corrupt label formatting, see efilabel in the "Arguments" section. ESCHEME=8 None or unsupported partitioning scheme detected in device. ENOPARTS=9 Neither a freebsd-boot nor an EFI boot partition was found on a se- lected device. EEFIBOOTMGR=10 Failed to run efibootmgr(8). ELOADER=11 Cannot read a required loader image. EMOUNT=12 Failed to mount the EFI boot partition. ECMD=13 Failed to execute a command during the update procedure. EEFIFILE=13 Invalid or conflicting EFI file destinations. EXAMPLES Run gpart(8) for a list of devices: gpart show Inspect the boot environment and the desired device: loaderupdate -P nvd0 Review the commands to execute: loaderupdate -D nvd0 Finally update the loaders for the device: loaderupdate nvd0 SEE ALSO bprintf(1), efibootmgr(8), gpart(8), gptboot(8), gptzfsboot(8), loader(8), uefi(8) HISTORY The loaderupdate command was added with the bsda2-0.4.0 release. AUTHORS Dominic Fandrey <freebsd@k4m1.org> CAVEATS Only supports GUID Partition Table formatted devices. FreeBSD ports 15.quarterly 13 June, 2025 LOADERUPDATE(8)
NAME | SYNOPSIS | DESCRIPTION | ENVIRONMENT | FILES | EXIT STATUS | EXAMPLES | SEE ALSO | HISTORY | AUTHORS | CAVEATS
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=loaderupdate&sektion=8&manpath=FreeBSD+Ports+15.1.quarterly>