NAME

loaderupdate — update boot loaders

SYNOPSIS

loaderupdate [-d destdir] [-L efilabel] [-b bootloader] [-e efiloader] [-o efifile] [-p pmbr] [-cDn] device ...

loaderupdate [-d destdir] [-L efilabel] [-b bootloader] [-e efiloader] [-o efifile] [-p pmbr] [-cDn] -a

loaderupdate [-d destdir] [-L efilabel] [-b bootloader] [-e efiloader] [-o efifile] [-p pmbr] [-cn] -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 overridden by the -b, -e and -p parameters. Which boot loaders are used by default also depends on the file system 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 environment variable, or the -d parameter.

The BOOTSTRAPPING section of gpart(8) provides a good overview of the boot process.

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 default is either /boot/gptboot or /boot/gptzfsboot, depending on the file system 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 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 locations, 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.

-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) command. 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 configuration 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 extracting the version, machine and ostype symbols from the kernel binary.
/boot/gptboot: The freebsd-boot partition image for booting from UFS, see gptboot(8).
/boot/gptzfsboot: The freebsd-boot partition image for booting from ZFS, see gptboot(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.

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 selected 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

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.