NAME

loaderupdate —

update boot loaders

SYNOPSIS

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

loaderupdate [-d destdir] [-L efilabel] [-b bootloader] [-e efiloader] [-p pmbr] [-Dn] -a

loaderupdate [-d destdir] [-L efilabel] [-b bootloader] [-e efiloader] [-p pmbr] [-n] -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 /.

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

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: Override the default freebsd-boot loader image.
-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: Override the default boot environment.
-e --efiloader efiloader: Override the default efi loader image.
-L --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.
-P --dump: Instead of performing boot loader updates print a summary of the boot environment and selected devices.
-p --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.

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.