EFI(8)

EFI(8) | System Manager's Manual | EFI(8)

# NAME

`efi` — UEFI variable editor

# SYNOPSIS

`efi` | [`-CcDFfhNOqrTVvy`] [`--brief`] [`--debug`[`=`num]] [`-@` file] [`-A` [hexnum]] [`-a` [hexnum]] [`-B` [hexnum]] [`-b` hexnum] [`-d` disk] [`-G` [dev]] [`-L` label] [`-l` loader] [`-n` hexnum] [`-o` hexnum[`,`hexnum ...]] [`-p` num] [`-R` regexp] [`-t` seconds] [`-w` [sig]] [`-X` hexnum[`,`hexnum ...]] [`-x` hexnum[`,`hexnum ...]]

# DESCRIPTION

`efi` can display all UEFI variables visible at runtime. It can also create, modify, and delete boot related variables such as Boot####, BootOrder, BootNext, Driver####, DriverOrder, SysPrep####, and SysPrepOrder. It is designed to be API compatible with `efibootmgr` in Linux, so that `grub` can be installed from NetBSD. Future features may be coming.

Many `efi` options require a number (####) indicating which “Boot####” argument to modify. Many options take this as an argument, but it can also be set with the `-b` option. Note that the boot number is a hexadecimal in the range of 0 to 0xFFFF. It need not have a leading ‘0x’ prefix and it need not be zero padded to 4 hexdigits. By default, the boot number specifies the “Boot####” variable, but the `-r` and `-y` options can override this so that it applies to the “Driver####” and “SysPrep####” variables.

The following options are currently available:

`--brief`
  Only show the variable name, UUID, attributes, and datasize that appear in the efi_var_ioc data structure (see `<sys/efiio.h>`). This is used when the structure of the data is not known by `efi`.
`--debug`[`=`num]
  Increment the debug level or set it to num when given. Its value is bit-mapped:

  - Bit(0): Show data structure.
  - Bit(1): Show raw data.
  - Bit(2): Show efi_var_ioc structure info (see `--brief`).
`-@`, `--append-binary-args`
  Append content of file (use ‘`-`’ for stdin) to the variable data. This data is passed to the boot loader on its command line.
`-A`, `--inactive` [####]
  Set given Boot#### variable inactive.
`-a`, `--active` [####]
  Set given Boot#### variable active.
`-B`, `--delete-bootnum` [####]
  Delete the Boot#### variable.
`-b`, `--bootnum` ####
  Specify the boot number (i.e., the #### in Boot####) to use with other options.
`-C`, `--create-only`
  Create a new Boot#### variable.
`-c`, `--create`
  Same as `-C`, but add the bootnum to the bootorder.
`-D`, `--remove-dups`
  Remove any duplicate BootOrder entries, retaining the first one in the list.
`-d`, `--disk` [dev]
  Specify the device containing the boot loader. The default is the device containing the current directory.
`-F`, `--no-reconnect`
  Do not force a devices reconnect after loading a driver.
`-f`, `--reconnect`
  Force a reconnect of devices after loading a driver. This has no effect for non-Driver#### variables.
`-G`, `--show-gpt` [dev]
  Show the GPT for the specified device. The default is the device containing the current directory. This currently assumes a widescreen for a readable display.
`-L`, `--label` LABEL
  Label name displayed by the boot manager. Defaults to ‘`NetBSD`’.
`-l`, `--loader` NAME
  Pathname of the boot loader relative to the specified partition. Defaults to \EFI\NetBSD\grub.efi. Note: EFI partitions are usually formatted as MSDOS partitions. Hence, the file separator is a backslash and may need to be escaped from the shell.
`-N`, `--delete-bootnext`
  Delete the BootNext variable.
`-n`, `--bootnext` ####
  Set the BootNext variable to Boot####.
`-O`, `--delete-bootorder`
  Delete the BootOrder variable.
`-o`, `--bootorder` ####[`,`#### ...]
  Set the BootOrder variable. The argument is a non-empty comma separated list of hex values. The hex values can range from 0 to FFFF and should correspond to one of the Boot#### variables.
`-p`, `--part` PART
  Specify the partition index on the device that contains the bootloader binary. Normally, this is the 'EFI' partition. The default is partition index 1.
`-q`, `--quiet`
  Run quietly — no output. (XXX: not yet).
`-r`, `--driver`
  Operate on Driver#### variables instead of Boot#### variables.
`-T`, `--delete-timeout`
  Delete Timeout variable.
`-t`, `--timeout` secs
  Set the boot manager Timeout variable, in seconds.
`-V`, `--version`
  Print version string and exit. To keep `grub-install` happy, this is currently set to version 18.
`-v`, `--verbose`
  Increment verboseness. This may be used multiple times. It is also passed directly to the GPT routines used by the `-G` and `-w` options.
`-w`, `--write-signature` [sig]
  For MBR disks: If the MBR partition is missing a signature (i.e., is zero), set it to a random value. If the sig argument is specified, then set the MBR signature to that value overriding any previous setting. The signature is a four byte value and can be specified in hex, octal, or decimal. This takes precedence over all other options except `-c`.
`-X`, `--remove-bootorder` ####[`,`#### ...]
  Remove argument(s) from the BootOrder variable.
`-x`, `--prefix-bootorder` ####[`,`#### ...]
  Prefix argument(s) to the BootOrder variable.
`-y`, `--sysprep`
  Operate on SysPrep#### variables instead of Boot#### variables.

# IMPLEMENTATION NOTES

`efi` requires kernel EFI runtime support and the device /dev/efi. Currently, `efi` only runs on little-endian machines, as required by the UEFI specification.

As of grub-install 2.12, the following `efibootmgr` options are used (see grub-2.12/grub-core/osdep/unix/platform.c):

- `-B`
- `-L` efi_distributor
- `-b` bootnum
- `-c`
- `-d` efidir_disk
- `-l` efifile_path
- `-p` efidir_part_idx
- `-q`
- `-w`
- `--version`

Currently, the following `efibootmgr` options are not implemented in `efi`:

- `-E`, `--edd-device`
- `-e`, `--edd`
- `-e`, `--edd30`
- `--file-dev-path`
- `--full-dev-path`
- `-g`, `--gpt`
- `-i`, `--iface`
- `-M`, `--mirror-above-4G`
- `-m`, `--mirror-below-4G`
- `-u`, `--unicode`, `--UCS-2`

The following options in `efi` are not in `efibootmgr`:

- `--brief`
- `--debug`
- `-G`, `--show-gpt`
- `-X`, `--remove-bootorder`
- `-x`, `--prefix-bootorder`

In addition, several of the supported `efibootmgr` options now take optional arguments or comma delimited hex number arguments for convenience.

# SEE ALSO

gpt(8)

# STANDARDS

`efi` attempts to follow version 2.10 Errata A (Aug 8, 2024) of the UEFI Specification (http://uefi.org).

# HISTORY

`efi` was intended to be a NetBSD replacement for `efibootmgr` in Linux. The later is required by `grub-install` in the `grub` package. As a result, the interface is the same with a few exceptions. For `efi` to be used with `grub-install` it obviously needs to be renamed or linked to `efibootmgr`.

# BUGS

Probably way too many to list. Currently, `efi` has had very limited testing. Use it at your own risk!

February 23, 2025 | NetBSD 11.0