8.13 Bootloader Configuration

The operating system supports multiple bootloaders. The bootloader is configured using bootloader-configuration declaration. All the fields of this structure are bootloader agnostic except for one field, bootloader that indicates the bootloader to be configured and installed.

Some of the bootloaders do not honor every field of bootloader-configuration. For instance, the extlinux bootloader does not support themes and thus ignores the theme field.

Data Type: bootloader-configuration

The type of a bootloader configuration declaration.

bootloader

The bootloader to use, as a bootloader object. For now grub-bootloader, grub-efi-bootloader, extlinux-bootloader and u-boot-bootloader are supported.

grub-efi-bootloader allows to boot on modern systems using the Unified Extensible Firmware Interface (UEFI). This is what you should use if the installation image contains a /sys/firmware/efi directory when you boot it on your system.

grub-bootloader allows you to boot in particular Intel-based machines in “legacy” BIOS mode.

Available bootloaders are described in (gnu bootloader …) modules. In particular, (gnu bootloader u-boot) contains definitions of bootloaders for a wide range of ARM and AArch64 systems, using the U-Boot bootloader.

target

This is a string denoting the target onto which to install the bootloader.

The interpretation depends on the bootloader in question. For grub-bootloader, for example, it should be a device name understood by the bootloader installer command, such as /dev/sda or (hd0) (see Invoking grub-install in GNU GRUB Manual). For grub-efi-bootloader, it should be the mount point of the EFI file system, usually /boot/efi.

menu-entries (default: ())

A possibly empty list of menu-entry objects (see below), denoting entries to appear in the bootloader menu, in addition to the current system entry and the entry pointing to previous system generations.

default-entry (default: 0)

The index of the default boot menu entry. Index 0 is for the entry of the current system.

timeout (default: 5)

The number of seconds to wait for keyboard input before booting. Set to 0 to boot immediately, and to -1 to wait indefinitely.

keyboard-layout (default: #f)

If this is #f, the bootloader’s menu (if any) uses the default keyboard layout, usually US English (“qwerty”).

Otherwise, this must be a keyboard-layout object (see Keyboard Layout).

Note: This option is currently ignored by bootloaders other than grub and grub-efi.

theme (default: #f)

The bootloader theme object describing the theme to use. If no theme is provided, some bootloaders might use a default theme, that’s true for GRUB.

terminal-outputs (default: 'gfxterm)

The output terminals used for the bootloader boot menu, as a list of symbols. GRUB accepts the values: console, serial, serial_{0-3}, gfxterm, vga_text, mda_text, morse, and pkmodem. This field corresponds to the GRUB variable GRUB_TERMINAL_OUTPUT (see Simple configuration in GNU GRUB manual).

terminal-inputs (default: '())

The input terminals used for the bootloader boot menu, as a list of symbols. For GRUB, the default is the native platform terminal as determined at run-time. GRUB accepts the values: console, serial, serial_{0-3}, at_keyboard, and usb_keyboard. This field corresponds to the GRUB variable GRUB_TERMINAL_INPUT (see Simple configuration in GNU GRUB manual).

serial-unit (default: #f)

The serial unit used by the bootloader, as an integer from 0 to 3. For GRUB, it is chosen at run-time; currently GRUB chooses 0, which corresponds to COM1 (see Serial terminal in GNU GRUB manual).

serial-speed (default: #f)

The speed of the serial interface, as an integer. For GRUB, the default value is chosen at run-time; currently GRUB chooses 9600 bps (see Serial terminal in GNU GRUB manual).

Should you want to list additional boot menu entries via the menu-entries field above, you will need to create them with the menu-entry form. For example, imagine you want to be able to boot another distro (hard to imagine!), you can define a menu entry along these lines:

(menu-entry
  (label "The Other Distro")
  (linux "/boot/old/vmlinux-2.6.32")
  (linux-arguments '("root=/dev/sda2"))
  (initrd "/boot/old/initrd"))

Details below.

Data Type: menu-entry

The type of an entry in the bootloader menu.

label

The label to show in the menu—e.g., "GNU".

linux

The Linux kernel image to boot, for example:

(file-append linux-libre "/bzImage")

For GRUB, it is also possible to specify a device explicitly in the file path using GRUB’s device naming convention (see Naming convention in GNU GRUB manual), for example:

"(hd0,msdos1)/boot/vmlinuz"

If the device is specified explicitly as above, then the device field is ignored entirely.

linux-arguments (default: ())

The list of extra Linux kernel command-line arguments—e.g., ("console=ttyS0").

initrd

A G-Expression or string denoting the file name of the initial RAM disk to use (see G-Expressions).

device (default: #f)

The device where the kernel and initrd are to be found—i.e., for GRUB, root for this menu entry (see root in GNU GRUB manual).

This may be a file system label (a string), a file system UUID (a bytevector, see File Systems), or #f, in which case the bootloader will search the device containing the file specified by the linux field (see search in GNU GRUB manual). It must not be an OS device name such as /dev/sda1.

For now only GRUB has theme support. GRUB themes are created using the grub-theme form, which is not documented yet.

Scheme Variable: %default-theme

This is the default GRUB theme used by the operating system if no theme field is specified in bootloader-configuration record.

It comes with a fancy background image displaying the GNU and Guix logos.