# Limine configuration file

## Location of the config file

Limine scans for the config file on *the boot drive*. On EFI, the volume
containing the EFI executable of the booted Limine is scanned first. The
drive is then scanned as a whole, followed by every partition sequentially -
first partition first, last partition last. On each volume the candidates are
tried in this order: on EFI, `<EFI app path>/limine.conf` first, or
`/EFI/BOOT/limine.conf` where that path cannot be determined; then
`/boot/limine/limine.conf`, `/boot/limine.conf`, `/limine/limine.conf`, and
`/limine.conf`.

These names are matched case insensitively; see [Paths](#paths) for how paths
elsewhere in the config file are matched.

Once the file is located, Limine will use it as its config file. Other possible
candidates in subsequent partitions or directories are ignored.

It is thus imperative that the intended config file is placed in a location
that will not be shadowed by another candidate config file.

On EFI, should Limine fail to determine which volume it was booted from, it
reports the condition as a bug and waits for a keypress. It then scans every
volume it can see, for `/EFI/limine/limine.conf` and `/EFI/BOOT/limine.conf`
before the four names above.

### Config via SMBIOS

Alternatively, if present, Limine considers first and foremost configurations
supplied to it as SMBIOS OEM String entries (Type 11). Such configurations are
accepted if the first string of such an entry starts with the prefix of
`limine:config:`. The rest of the string is taken as the config file. If such a
configuration is found, no further scanning for config files is done. As such,
in this SMBIOS-provided config file scenario, the `boot():` drive is undefined
on BIOS, and set to the boot device of Limine on UEFI.

## Structure of the config file

The Limine configuration file is comprised of *menu entries* and *options*.
Comments begin in '#' and can only be on their own lines.

### Menu entries and sub-entries

*Menu entries* describe *entries* which the user can select in the *boot menu*.

A *menu entry* is opened by a line starting with `/` followed by a
newline-terminated string, that being the title of the entry which the user
will see.
Any *local option* that comes after it, and before another *menu entry*, or
the end of the file, will be part of that *menu entry*.

A *menu entry* can be a directory, meaning it can hold sub-entries. In order
for an entry to become a directory, it needs to have a sub-entry following
right after it.
(A `comment` option may be present between the beginning of the directory entry
and the beginning of the sub-entry).

A *sub-entry* is a menu entry started with a number of `/` greater than 1
prepended to it.
Each `/` represents 1 level deeper down the tree hierarchy of directories and
entries.

Directories can be expanded (meaning they will not show up as collapsed in the
menu) by default if a `+` is put between the `/`s and the beginning of the
entry's title.

### Options

*Options* are simple `option_name: string...` style "assignments".
The string can have spaces and other special characters, without requiring
quotations. New lines are delimiters. Option names are not case sensitive.
An option's value is truncated at 4095 characters.

Some *options* are part of an entry (*local*), some other options are *global*.
*Global options* can appear anywhere in the file and are not part of an entry,
although usually one would put them at the beginning of the config.
Some *local options* work the same between entries using any *protocol*, while
other *local options* are specific to a given *protocol*.

Some options take *paths* as strings; these are described in the next section.

*Global options* are:

Miscellaneous:

* `timeout` - Specifies the timeout in seconds before the selected *entry* is
  automatically booted (see `default_entry` option). Decimal values such as
  `0.25` are accepted, and the timeout is capped at `9999` seconds. If set to
  `no`, disable automatic boot. If set to `0`, boot the selected entry
  instantly, without showing the menu. A value that is neither `no` nor a
  number is treated as `0`. On UEFI, the Boot Loader Interface's
  `LoaderConfigTimeoutOneShot` EFI variable, where set (for example by
  `systemctl reboot --boot-loader-menu=`), overrides this option for the boot
  that consumes it, and the persistent `LoaderConfigTimeout` variable (for
  example from `bootctl set-timeout`) is honoured only where this option is
  not set.
* `quiet` - If set to `yes`, enable quiet mode, where all screen output except
  panics and important warnings is suppressed. If `timeout` is not 0, the
  `timeout` still occurs, and pressing any key during the timeout will reveal
  the menu and disable quiet mode.
* `serial` - If set to `yes`, enable serial I/O for the bootloader.
* `serial_baudrate` - If `serial` is set to `yes`, this specifies the baudrate
  to use for serial I/O. Defaults to `115200`, which is also the maximum. The
  minimum is `50`, and the rate must divide `115200` exactly, which every
  standard rate in that range does except `110`, `2000` and `56000`; any other
  value is treated as `115200`. BIOS only, ignored with Limine UEFI.
* `global_dtb` - If set, use this DTB instead of the firmware-provided DTB for
  Limine itself, as well as for any booted entry whose protocol supports DTBs
  and the DTB is not locally overridden with `dtb_path`.
* `default_entry` - Entry which will be automatically selected at startup.
  Can be a 1-based entry index (e.g. `1`), or an entry path (e.g.
  `OSes/Arch Linux`). Entry paths use `/` as a directory separator; literal
  `/`, `\`, and `#` characters in entry names must be escaped as `\/`, `\\`,
  and `\#` respectively. If multiple sibling entries share the same name, append
  `#N` to select the Nth duplicate (e.g. `Arch Linux#1` for the second entry
  named `Arch Linux`). If unspecified, it is `1`. On UEFI, a Boot Loader
  Interface `LoaderEntryOneShot` request takes precedence over this option, and
  so does `remember_last_entry` where it has an entry to restore. The
  persistent `LoaderEntryDefault` variable is consulted only where this option
  is not set. A value that does not name a bootable entry still counts as set,
  but disables autoboot (and shows the menu if `timeout` is `0` and/or `quiet`
  is `yes`): that covers a path or index matching nothing, and a path or index
  naming a directory.
* `remember_last_entry` - If set to `yes`, remember last booted entry. Takes
  precedence over `default_entry` and over the persistent `LoaderEntryDefault`
  variable; `default_entry` applies only where this option is `no` or no
  remembered entry resolves. (UEFI only).
* `graphics` - If set to `no`, force text mode for the boot menu, else use
  a video mode.
* `wallpaper` - Path to a file to use as a wallpaper. BMP, PNG, JPEG, and QOI
  formats are supported. There can be multiple of this option, in which case
  the wallpaper will be randomly selected from the provided options.
* `wallpaper_style` - The style which will be used to display the wallpaper
  image: `tiled`, `centered`, or `stretched`. Default is `stretched`.
* `backdrop` - When the background style is `centered`, this specifies the
  colour of the backdrop for parts of the screen not covered by the background
  image, in RRGGBB format.
* `verbose` - If set to `yes`, print additional information during boot.
  Defaults to not verbose.
* `terse` - If set to `yes`, suppress informational loading messages (such as
  "Loading kernel" and "Loading module") when booting any entry. The menu and
  any error or panic messages remain unaffected. Defaults to `no`.
* `randomise_memory` - If set to `yes`, randomise the contents of RAM at bootup
  in order to find bugs related to non zeroed memory or for security reasons.
  This option will slow down boot time significantly. In the case of IA-32,
  BIOS or UEFI, this will only randomise memory below 4GiB.
* `randomize_memory` - Alias of `randomise_memory`.
* `hash_mismatch_panic` - If set to `no`, do not panic if there is a hash
  mismatch for a file. A warning is printed and Limine then waits for a
  keypress: `Y` continues the boot, any other key returns to the menu. Forced
  to `yes` when Secure Boot is active and a config hash is enrolled.
* `measured_boot` - If set to `yes`, opt in to measured boot. Forced to `yes`
  when Secure Boot is active and a config hash is enrolled, and forced back to
  `no` if the firmware does not expose a TPM 2.0/CC measurement interface. See
  [USAGE.md](USAGE.md#measured-boot).
* `firmware_logo` - If set to `yes`, restore the OEM firmware boot logo upon
  handoff to the OS, instead of leaving a blank screen, by clearing the
  "displayed" status bit in the ACPI BGRT table so the OS redraws the logo
  itself. The image is re-centred for the active resolution. UEFI only;
  defaults to `no`.
* `keyboard_layout` - Specifies a keyboard layout to remap printable
  keystrokes to before they reach the menu and editor. Currently only
  `dvorak` and `azerty` are supported. If unset, no remapping is applied
  and keystrokes are used as-is. This assumes the underlying firmware
  resolves keystrokes as US-QWERTY; on firmware/keyboard combinations that
  already resolve a different layout natively, this option may produce
  incorrect output.
* `mouse` - If set to `no`, disable mouse support in the boot menu. Defaults
  to `yes`, in which case, if a mouse is present, the menu selection follows
  the pointer, left clicking an entry boots it (or expands a directory), and
  the scroll wheel moves the selection. Using the mouse stops the `timeout`
  countdown, as pressing a key does. On BIOS this uses the PS/2 (or emulated
  PS/2) mouse; on UEFI any pointer device the firmware exposes.

Limine interface control options:

* `interface_resolution` - Specify screen resolution to be used by the Limine
  interface (menu, editor, console...) in the form `<width>x<height>`. This
  will *only* affect the Limine interface, not any booted OS. If not specified,
  Limine will pick a resolution automatically. If the resolution is not
  available, Limine will pick another one automatically. Ignored if using text
  mode.
* `interface_rotation` - Specifies the rotation of the Limine interface.
  It can be any of the following values: `0`, `90`, `180`, `270`. Default is `0`.
* `interface_branding` - A string that will be displayed on top of the Limine
  interface.
* `interface_branding_colour` - An `RRGGBB` hexadecimal value specifying the
  colour of the branding string. Default is `00aaaa`.
* `interface_branding_color` - Alias of `interface_branding_colour`.
* `interface_help_hidden` - Hides the help text located at the top of the
  screen showing the key bindings.
* `interface_help_colour` - An `RRGGBB` hexadecimal value specifying the
  colour of the help strings. Default is `00aa00`.
* `interface_help_color` - Alias of `interface_help_colour`.
* `interface_help_colour_bright` - An `RRGGBB` hexadecimal value specifying
  the brighter accent colour used for the auto-boot countdown digit. If
  unspecified, it is derived from `interface_help_colour` by adding `0x55`
  to each channel (saturating at `0xff`).
* `interface_help_color_bright` - Alias of `interface_help_colour_bright`.

Limine graphical terminal control options:

These are ignored if using text mode.

* `term_font` - Path to a font file to be used instead of the default one for
  the menu and terminal. The font file must be a code page 437 character set
  comprised of 256 consecutive glyph bitmaps. Each glyph's bitmap must be
  expressed left to right (1 byte per row), and top to bottom (16 bytes per
  whole glyph by default; see `term_font_size`). See e.g. the
  [VGA text mode font](https://github.com/viler-int10h/vga-text-mode-fonts)
  collection for fonts.
* `term_font_size` - The size of each glyph of the font in dots, which must
  correspond to the font file, or display will be garbled or loading issues
  will occur. All fonts are assumed to be of width 8, so the first value of
  the pair (AKA the `8` in `8x16`) must be `8`; any other width is refused and
  the default font is used in place of `term_font`. To set horizontal spacing
  between glyphs on screen, see `term_font_spacing`. Defaults to `8x16`.
  Ignored if `term_font` not set or if the font fails to load.
* `term_font_scale` - Scaling for the font in the x and y directions. `2x2`
  would display the font in double size, which is useful on high-DPI displays
  at native resolution. `2x1` only makes the font twice as wide, similar to the
  VGA 40 column mode. `4x2` might be good for a narrow font on a high
  resolution display. Each factor must be between 1 and 8; any value that is not
  such a pair is treated as if the option were unset. If unset, the scaling
  follows the resolution: `1x1` below 2560x1440, `2x2` from there, and `4x4`
  from 5120x2880.
* `term_font_spacing` - Horizontal spacing, in pixels, between glyphs on
  screen. Also applies to the built-in Limine font. Defaults to 1. 0 is
  allowed; a value above 8, or one that is not a number, is treated as if the
  option were unset.
* `term_palette` - Specifies the colour palette used by the terminal (RRGGBB).
  It is a `;` separated array of 8 colours: black, red, green, brown, blue,
  magenta, cyan, and gray. Ignored if not using a graphical terminal.
* `term_palette_bright` - Specifies the bright colour palette used by the
  terminal (RRGGBB). It is a `;` separated array of 8 bright colours:
  dark gray, bright red, bright green, yellow, bright blue, bright magenta,
  bright cyan, and white. Ignored if not using a graphical terminal.
* `term_background` - Terminal text background colour (TTRRGGBB). TT stands for
  transparency. Defaults to `00000000`, or to `80000000` when a `wallpaper` is
  displayed.
* `term_foreground` - Terminal text foreground colour (RRGGBB).
* `term_background_bright` - Terminal text background bright colour (RRGGBB).
* `term_foreground_bright` - Terminal text foreground bright colour (RRGGBB).
* `term_margin` - Set the amount of margin, in pixels, around the terminal.
  Defaults to `0`, or to `64` when a `wallpaper` is displayed.
* `term_margin_gradient` - Set the thickness in pixel for the gradient around
  the terminal. Clamped to `term_margin`. Defaults to `0`, or to `4` when a
  `wallpaper` is displayed.

Editor control options:

* `editor_enabled` - If set to `no`, the editor will not be accessible.
  Defaults to `yes` unless a config hash is enrolled. Unconditionally
  disabled when Secure Boot is active and a config hash is enrolled.
* `editor_highlighting` - If set to `no`, syntax highlighting in the editor
  will be disabled. Defaults to `yes`.
* `editor_validation` - If set to `no`, the editor will not alert you about
  invalid options or syntax errors. Defaults to `yes`.

*Locally assignable (non protocol specific) options* are:

* `comment` - An optional comment string that will be displayed by the
  bootloader on the menu when an entry is selected.
* `protocol` - The boot protocol that will be used to boot the
  kernel/executable. Valid protocols are: `linux`, `limine`, `multiboot`
  (or `multiboot1`), `multiboot2`, `efi`, `efi_boot_entry` and `bios`.
* `cmdline` - The command line string to be passed to the kernel/executable.
  Can be omitted.
* `kernel_cmdline` - Alias of `cmdline`.
* `if_fw_type` - Hide the entry if the firmware does not match. Valid values
  are: `BIOS`, `UEFI`
* `if_arch` - Hide the entry if the current CPU architecture is not in the
  space separated list of permitted architectures
    * see the `ARCH` macro in [Built-in macros](#built-in-macros) for a list of possible architectures
* `if_loader_arch` - Hide the entry if the Limine binary's own architecture is
  not in the space separated list of permitted architectures
    * see the `LOADER_ARCH` macro in [Built-in macros](#built-in-macros) for details

> **NOTE:** `uefi` and `efi_chainload` are aliases of the `efi` protocol
> option. `bios_chainload` is an alias of the `bios` protocol option.

> **NOTE:** BIOS chainloading entries will be hidden when booting using UEFI
> and vice-versa.

*Locally assignable (protocol specific) options* are:

* Linux protocol:
  * `path` - The path of the kernel.
  * `kernel_path` - Alias of `path`.
  * `module_path` - The path to a module (such as initramfs). This option can
    be specified multiple times to specify multiple modules.
  * `resolution` - The resolution to be used. This setting takes the form of
    `<width>x<height>x<bpp>`. If the resolution is not available, Limine will
    pick another one automatically. Omitting `<bpp>` will default to 32.
  * `textmode` - If set to `yes`, prefer text mode. (BIOS only)
  * `dtb_path` - A device tree blob to pass instead of the one provided by the
    firmware.

* Limine protocol:
  * `path` - The path of the executable.
  * `kernel_path` - Alias of `path`.
  * `module_path` - The path to a module. This option can be specified multiple
    times to specify multiple modules.
  * `module_string` - A string to be associated with a module. This option can
    also be specified multiple times. It applies to the module described by the
    last module option specified.
  * `module_cmdline` - Alias of `module_string`.
  * `resolution` - The resolution to be used. This setting takes the form of
    `<width>x<height>x<bpp>`. If the resolution is not available, Limine will
    pick another one automatically. Omitting `<bpp>` will default to 32.
  * `kaslr` - For relocatable executables, if set to `yes`, enable kernel
    address space layout randomisation. KASLR is disabled by default.
  * `randomise_hhdm_base` - If set to `yes`, randomise the base address of the
    higher half direct map. If set to `no`, do not. By default it is `yes` if
    KASLR is supported and enabled, else it is `no`.
  * `randomize_hhdm_base` - Alias of `randomise_hhdm_base`.
  * `max_paging_mode`, `min_paging_mode` - Limit the maximum and minimum paging
    modes to one of the following:
    - x86-64 and aarch64: `4level`, `5level`.
    - riscv64: `sv39`, `sv48`, `sv57`.
    - loongarch64: `4level`.
  * `paging_mode` - Equivalent to setting both `max_paging_mode` and
    `min_paging_mode` to the same value.
  * `dtb_path` - A device tree blob to pass instead of the one provided by the
    firmware.

* multiboot1 and multiboot2 protocols:
  * `path` - The path of the executable.
  * `kernel_path` - Alias of `path`.
  * `module_path` - The path to a module. This option can be specified multiple
    times to specify multiple modules.
  * `module_string` - A string to be passed to a module. This option can also
    be specified multiple times. It applies to the module described by the last
    module option specified.
  * `resolution` - The resolution to be used should the executable request a
    graphical framebuffer. This setting takes the form of
    `<width>x<height>x<bpp>` and *overrides* any resolution requested by the
    executable. If the resolution is not available, Limine will pick another
    one automatically. Omitting `<bpp>` will default to 32.
  * `textmode` - If set to `yes`, prefer text mode. (BIOS only)

* EFI Chainload protocol:
  * `path` - Path of the EFI application to chainload.
  * `image_path` - Alias of `path`.
  * `resolution` - The resolution to be used. This setting takes the form of
    `<width>x<height>x<bpp>`. If the resolution is not available, Limine will
    pick another one automatically. Omitting `<bpp>` will default to 32.

* EFI Boot Entry protocol:
  * `entry` - The name of the EFI boot entry to reboot into.

* BIOS Chainload protocol:
  * `drive` - The 1-based drive to chainload, if omitted, assume boot drive.
    Only hard disks can be chainloaded, so this is always a hard disk index;
    booted from optical media, an omitted `drive` therefore selects the hard
    disk of the same index rather than the boot medium.
  * `partition` - The 1-based partition to chainload, if omitted, or set to 0,
    chainload drive (MBR).
  * `mbr_id` - Optional. If passed, use an MBR ID (32-bit hex value) to
    identify the drive containing the volume to chainload. Overrides `drive`,
    if present, but does *not* override `partition`.
  * `gpt_uuid` or `gpt_guid` - Optional. If passed, use the GPT GUID to
    identify the drive containing the volume to chainload. Overrides `drive`
    and `mbr_id`, if present, but does *not* override `partition`.

  To boot FreeBSD on a BIOS/GPT disk, point `partition` at the `freebsd-boot`
  partition. Limine recognises it by its GPT type GUID and emulates FreeBSD's
  `pmbr`: it loads the whole partition (`gptboot`) and hands off to it, rather
  than treating it as a conventional boot record (which it is not, as it has no
  `0xAA55` signature).

## Paths

A Limine path is used to locate files in the whole system. It is comprised of
a *resource*, a *resource argument*, and a *path*. It takes the form of:
```
resource(argument):/path
```

The format for `argument` changes depending on the resource used.

A resource can be one of the following:
* `boot` - If booted off PXE this is an alias of `tftp`. Else the `argument` is
  the 1-based decimal value representing the partition on the boot drive
  (values of 5+ for MBR logical partitions). If omitted, the partition
  containing the configuration file on the boot drive is used.
  For example: `boot(2):/...` will use partition 2 of the boot drive and
  `boot():/...` will use the partition containing the config file on the boot
  drive.
* `hdd` - Hard disk drives. The `argument` takes the form of `drive:partition`;
  for example: `hdd(3:1):/...` would use hard drive 3, partition 1. Partitions
  and drives are both 1-based (partition values of 5+ for MBR logical
  partitions). Omitting the partition is possible;
  for example: `hdd(2:):/...`. Omitting the partition will access the entire
  volume instead of a specific partition (useful for unpartitioned media).
* `odd` - Optical disk drives (CDs/DVDs/...). The `argument` takes the form of
  `drive:partition`; for example: `odd(3:1):/...` would use optical drive 3,
  partition 1. Partitions and drives are both 1-based (partition values of 5+
  for MBR logical partitions). Omitting the partition is possible;
  for example: `odd(2:):/...`. Omitting the partition will access the entire
  volume instead of a specific partition (useful for unpartitioned media, which
  is often the case for optical media).
* `guid` - The `argument` takes the form of a GUID/UUID, such as
  `guid(736b5698-5ae1-4dff-be2c-ef8f44a61c52):/...`. The GUID is that of either
  a filesystem, when available, or a GPT partition GUID, when using GPT, in a
  unified namespace.
* `uuid` - Alias of `guid`.
* `fslabel` - The `argument` is the name of the filesystem label of a
  partition, or of a whole volume where the filesystem occupies the entire
  medium. FAT volume labels and ISO 9660 volume identifiers are both read, and
  are matched case insensitively.
* `tftp` - The `argument` is the IP address of the tftp server to load the file
  from. If the argument is left empty (`tftp():/...`) the file will be loaded
  from the server Limine booted from. This resource is only available when
  booting off PXE.

Paths are matched case sensitively, with two exceptions. On FAT volumes a name
that fits the 8.3 short form is matched case insensitively, the short name
being stored uppercase; a name too long for that form is matched case
sensitively. On ISO9660 volumes a name carrying no Rock Ridge extension is
matched case insensitively, ISO9660 names being uppercase. The search for the
config file itself is case insensitive on every filesystem. Note that Joliet
supplementary volume descriptors are not read, so on an ISO9660 volume a long
name is only available through Rock Ridge.

For MBR, the four primary partitions take the numbers 1 to 4 by the slot they
occupy, whether or not that slot is used, and logical partitions are numbered
from 5 upwards by counting along the extended partition's chain. Every entry
with a non-zero size takes a number, except an entry of an extended type --
of which only the first non-empty one is the link to the next EBR -- and one
in an EBR's last two slots that falls outside either the extended partition
or the extent the link that led to that EBR declared.

A path can optionally be suffixed with a blake2b hash for the referenced file,
by appending a pound character (`#`) followed by the blake2b hash.
E.g.: `boot():/somemodule.tar#ca6914d2...446b470a`.
When Secure Boot is active and a config hash is enrolled, all file paths
**must** have a hash appended or Limine will panic (except for wallpapers and
fonts, which are silently skipped instead, falling back to defaults). Without
an enrolled hash Limine treats Secure Boot as inactive; see
[USAGE.md](USAGE.md#secure-boot).

A gzip-compressed resource is indicated by inserting a dollar character (`$`)
before the resource string. This allows for transparent decompression. For
such resources, the hash covers the consumed compressed gzip member bytes,
not the decompressed data and not trailing bytes outside the consumed member.
The hash thus authenticates the on-disk payload bytes Limine uses.

## Macros

Macros are strings that can be arbitrarily assigned to represent other strings.
For example:
```
${MY_MACRO}=Some text
```

Now, whenever `${MY_MACRO}` is used in the config file (except for an
assignment as above), it will be replaced by the text `Some text`. For example:
```
cmdline: something before ${MY_MACRO} something after
```

Macros must always be placed inside `${...}` where `...` is the arbitrary macro
name.

### Built-in macros

Limine automatically defines these macros:

* `ARCH` - This built-in macro expands to the architecture of the machine.
  Possible values are: `x86-64`, `ia-32`, `aarch64`, `riscv64`, `loongarch64`.
  In the case of IA-32, BIOS or UEFI, the macro will always expand to `x86-64`
  if the 64-bit extensions are available, else `ia-32`.
* `FW_TYPE` - This built-in macro expands to `UEFI` if booted using UEFI
  firmware, or `BIOS` if booted using legacy x86 BIOS.
* `LOADER_ARCH` - This built-in macro expands to the architecture of the Limine
  binary itself. Possible values are the same as `ARCH`: `x86-64`, `ia-32`,
  `aarch64`, `riscv64`, `loongarch64`. Unlike `ARCH`, this is determined at
  compile time and does not probe CPU capabilities; the IA-32 binary always
  expands to `ia-32` even on a CPU with 64-bit extensions.