Products › LamBoot › Docs › Configuration reference

Configuration reference

Every policy.toml key: default_entry, allowlist and denylist, crash_threshold, and the rest.

Overview

LamBoot is configured through several mechanisms:

Mechanism Location Purpose
policy.toml \EFI\LamBoot\policy.toml on ESP Boot behavior, security, UI, modules
manifest.toml \EFI\LamBoot\modules\manifest.toml on ESP Diagnostic module display names
SMBIOS OEM Strings QEMU/hypervisor config VM identity (VMID, fleet ID)
fw_cfg QEMU host config Host-injected runtime data
BLS Entries \loader\entries\*.conf on ESP Boot entry definitions

All configuration is optional. LamBoot works with sensible defaults out of the box.

policy.toml Reference

The policy file is at \EFI\LamBoot\policy.toml on the ESP. All fields are optional, and missing fields use defaults. The file uses TOML syntax with [section] headers.

When updating LamBoot via lamboot-install --update, the existing policy.toml is preserved. New defaults are written to policy.toml.new for reference.

Root-Level Options

Key Type Default Description
version integer 1 Config format version. Always 1.
default_timeout_ms integer 5000 Auto-boot delay in milliseconds. Set to 0 for no auto-boot (wait forever).
default_entry string (none) Entry ID to auto-boot. If unset, the first entry by sort order is selected.
default_pattern string (none) Glob over entry id. When set, the default selector picks the highest-version entry whose id matches the pattern, across all sort-key cohorts. Wins over default_entry when both are set and the pattern matches at least one entry. Mirrors sd-boot's escape hatch for distros that emit sort-key inconsistently (see Bug 22 and the cohort-split note below).
bls_ignore_sort_key boolean false When true, the sort comparison ignores the BLS sort-key field entirely and orders by version plus filename. Mirrors Fedora bootupd's choice and fixes both menu order and the default cursor when a distro mixes sort-key presence across kernels mid-upgrade. Spec deviation when on.

Entry IDs are derived from BLS filenames: fedora-6.19.9.conf becomes entry ID bls-fedora-6.19.9. For ESP-discovered entries: windows, grub, refind, fallback. For tools: tool-diag-shell, tool-pci-inventory, etc.

Cohort-split escape hatches. default_pattern and bls_ignore_sort_key exist for one real failure mode: a distro that emits sort-key on some kernels but not others (observed mid-upgrade on Debian forky/sid and Pop!_OS), which strands the wrong kernel at the top of the menu. Fresh v0.11.0+ installs ship the template with bls_ignore_sort_key = true; existing installs are left as-is and the new template lands at policy.toml.new. Either knob resolves it, and the runtime also surfaces a cohort-split notice when it detects the condition.

Example

default_timeout_ms = 10000
default_entry = "bls-fedora-6.19.9"

[security] Section

Key Type Default Description
secure_boot_required boolean false When true, logs a warning if Secure Boot is disabled. (Advisory only. This does not block boot.)
measured_boot boolean true Informational flag indicating TPM measurement is desired. (TPM measurement always runs when a TPM is present, regardless of this setting. It defaults on because it is free when a TPM exists and a no-op when it does not.)
crash_threshold integer 3 Number of failed boot attempts before crash loop fallback triggers.
fallback_order array [] Entry IDs to try during crash loop, in priority order. If empty or none match, the menu is shown for manual selection.
allowlist array [] Allowed EFI paths. If empty, all paths are allowed. Supports * wildcards.
denylist array [] Denied EFI paths. Overrides the allowlist. Supports * wildcards.

Crash Loop Example

[security]
crash_threshold = 3
fallback_order = ["bls-fedora-6.17.1", "fallback"]

If the system fails to boot 3 times in a row (without lamboot-mark-success.service running), LamBoot selects bls-fedora-6.17.1. If that entry doesn't exist, it tries fallback. If neither matches, the menu is shown.

Path Filtering Example

[security]
# Only allow Fedora and Windows entries
allowlist = ["\\EFI\\fedora\\*", "\\EFI\\Microsoft\\*", "\\EFI\\Linux\\*"]

# Block a known-bad kernel
denylist = ["\\EFI\\Linux\\vmlinuz-6.18.0-broken"]

Path matching is case-insensitive. Wildcards match any substring when placed at the start (*suffix), end (prefix*), or both (*middle*).

[ui] Section

Key Type Default Description
theme string "default" Color theme. Only "default" (Catppuccin Mocha) is currently available.
font_size string "medium" Font size: "small", "medium", "large". (Parsed today, with all sizes rendering at medium.)

[modules] Section

Key Type Default Description
enabled boolean true Enable discovery of diagnostic modules from \EFI\LamBoot\modules\. Set to false to hide all modules from the boot menu.

[watchdog] Section

Key Type Default Description
enabled boolean true Enable the UEFI watchdog timer. Prevents indefinite hangs during boot.
grace_seconds integer 15 Watchdog timeout in seconds. If LamBoot doesn't complete a phase within this time, the firmware resets the system.

[loader] Section (SDS-3, v0.9.0+)

Key Type Default Description
native_pe enum string "auto" Controls whether UKIs and Linux kernels are loaded via LamBoot's native Rust PE loader or firmware's BS->LoadImage plus BS->StartImage. Values: "auto", "always", "never" (case-insensitive).

Values

Value Behavior
"auto" (default) Native loader when ShimLock::Verify succeeds on the image bytes pre-load (and trivially on SB-off plus directly-signed setups). Falls back to firmware load when shim is present but rejects the bytes, or when no verify path is available.
"always" Always use the native loader, regardless of pre-load verification. Operator asserts trust without delegating to shim. Useful during SB-off validation where every binary is self-signed by the administrator's key chain.
"never" Always use BS->LoadImage. This matches v0.8.3 behavior and provides a one-flag rollback if the native loader ever hits an unexpected firmware quirk.

Why this exists

Firmware's BS->LoadImage invokes the Security2Arch hook for every image. Under shim 15.8, that hook depends on ShimLock being installed. Shim 15.8 uninstalls ShimLock after LoadImage-ing any child binary (for example a legacy UEFI FS driver). On stock Ubuntu/Debian/Fedora, that sequence meant LamBoot under Secure Boot could not verify kernels after having loaded an ext4 driver, which was the v0.8.3 VM 122 failure mode.

Post-SDS-3, the native loader reads PE bytes, validates against §5.1 of SPEC-NATIVE-PE-LOADER.md, allocates UEFI pages, applies relocations, installs LoadedImageProtocol, and transfers control via a raw function-pointer cast, with zero BS->LoadImage calls. ShimLock::Verify runs ONCE on the bytes before any of this, stamping the trust verdict that the image_loaded_native trust-log event records with the image's SHA-256. LamBoot loads the kernel itself rather than delegating to firmware LoadImage.

The Chainload path (Windows Boot Manager, GRUB, EFI Fallback) stays on the firmware path because those binaries may have imports that the native loader rejects by design (spec §5.2). Chainload's shim interaction is a different surface and falls outside SDS-3's target.

See docs/specs/SPEC-NATIVE-PE-LOADER.md for the full spec.

[drivers] Section (SDS-6, v0.9.0+)

Key Type Default Description
legacy_uefi_drivers enum string "auto" Controls loading of .efi filesystem drivers from \EFI\LamBoot\drivers\. Values: "auto", "always", "never" (case-insensitive).

Values

Value Behavior
"auto" (default) Load drivers only for filesystems LamBoot does not natively support. Skips ext4_*.efi, ext2_*.efi, ext3_*.efi because the native ext4 backend covers them, and skips btrfs because btrfs is read natively too. Drivers for xfs, ntfs, zfs, f2fs, iso9660 still load if their .efi binary is present.
"always" Load every driver in \EFI\LamBoot\drivers\, regardless of native coverage. This matches v0.8.3 behavior and is useful for A/B debugging; it preserves the shim-15.8 interaction pattern. Loading a natively-covered driver emits a legacy_driver_redundant trust event.
"never" Load no legacy drivers. Skip all, regardless of coverage. A security-conscious posture for systems whose filesystems are all natively covered: it asserts LamBoot will never LoadImage a third-party UEFI binary at boot. A required filesystem needs a native backend, otherwise the boot enumerating that volume will fail.

Why this exists

LamBoot v0.8.x loaded every driver in the drivers directory at every boot, via LoadImage plus StartImage under SecurityOverride. Each such load triggers shim 15.8 to uninstall ShimLock, preventing LamBoot from verifying kernels afterward. With the native ext4 reader (SDS-2) in v0.9.x, the ext4 driver is no longer needed for the 95%-of-users case: Auto mode removes it from the load path entirely, closing the shim-uninstall window for ext4-on-/boot systems.

See docs/specs/SPEC-UEFI-FSDRV-DEPRECATION.md for the full deprecation schedule.

[diagnostics] Section (v0.11.0+)

Key Type Default Description
verbose boolean false When true, LamBoot writes a full breadcrumb trace of the boot path to the audit log for troubleshooting. Default off, so no breadcrumbs are written. Turn on only to investigate a boot problem. On firmware with the conout_fat_coupling quirk the breadcrumbs are coalesced in RAM and flushed once before kernel handoff, so enabling this never adds FAT-write churn to the hang-prone band. 
[diagnostics]
verbose = true

Module Manifest

The file \EFI\LamBoot\modules\manifest.toml provides friendly display names for diagnostic modules. Without it, modules are shown as "Tool: filename".

Format

[modules.diag-shell]
name = "Diagnostic Shell"

[modules.pci-inventory]
name = "PCI Device Inventory"

[modules.mem-quick]
name = "Quick Memory Test"

[modules.nvme-diag]
name = "NVMe Health Check"

The section ID (for example diag-shell) matches the .efi filename without the extension. Only the name field is read. The working diagnostic modules today are diag-shell, pci-inventory, and mem-quick; nvme-diag is currently a stub and not yet implemented.

SMBIOS OEM Strings

LamBoot reads SMBIOS Type 11 (OEM Strings) to get host-injected identity information. Strings must use the format lamboot.KEY=VALUE.

Recognized Keys

Key Used In Description
lamboot.vmid GUI header, boot.json VM identifier (for example Proxmox VMID). Displayed prominently in the boot menu header.
lamboot.fleet-id boot.json Fleet or cluster identifier for grouping VMs in monitoring.

Additional keys (for example lamboot.role, lamboot.monitor) are stored in SMBIOS but not currently read by LamBoot. They can be used by host-side tooling like lamboot-monitor.py.

Setting OEM Strings

QEMU/KVM (direct):

qemu-system-x86_64 ... -smbios type=11,value=lamboot.vmid=201

Proxmox (VM config):

qm set 201 --args "-smbios type=11,value=lamboot.vmid=201"

Proxmox (automatic via hookscript): The LamBoot hookscript auto-injects the VMID on every VM start. See the Proxmox Guide.

Other hypervisors: Any method that sets SMBIOS Type 11 OEM strings will work. Consult your hypervisor documentation.

Bare metal: SMBIOS OEM strings are set by the hardware manufacturer. LamBoot reads them if present and treats them as optional.

fw_cfg Data Channel

On QEMU/KVM (x86_64 only), LamBoot reads the QEMU fw_cfg device for host-injected configuration:

fw_cfg File Description
opt/lamboot/config Arbitrary configuration string from the host
etc/vmgenid_guid VM Generation ID (used for snapshot detection)

Injecting fw_cfg Data

qemu-system-x86_64 ... -fw_cfg name=opt/lamboot/config,string="key1=value1;key2=value2"

The opt/lamboot/config file is logged at boot time. Its contents are available in the boot log and currently serve as a data channel for host-side integration rather than parsed configuration.

The VM Generation ID (etc/vmgenid_guid) is read automatically to detect snapshot restores and reset the crash counter.

BLS Entry Format

LamBoot discovers boot entries from BLS (Boot Loader Specification) Type 1 files at \loader\entries\*.conf on the ESP.

Recognized Fields

Field Required Description
title Yes Display name in the boot menu
version No Kernel version (used for sorting)
machine-id No Machine identifier
sort-key No Sort priority prefix (for example distro name)
linux Yes* Kernel path (relative to ESP root)
initrd No Initrd path(s), one per line. Multiple initrds supported.
efi Yes* EFI application path (alternative to linux)
options No Kernel command line arguments. Multiple options lines are concatenated.
architecture No Target architecture (for example x64, aa64). Entries for other architectures are hidden.

*Either linux or efi is required.

Boot Counting

BLS entries support boot assessment via filename suffixes:

  • entry+3.conf: 3 tries remaining, entry is being assessed
  • entry+0-2.conf: 0 tries remaining, 2 attempts made, entry failed assessment
  • entry.conf: no counters, entry is known good

LamBoot decrements the counter on each boot attempt. When tries reach 0, the entry is considered failed and sorted to the bottom.

Sort Order

Entries are sorted using the UAPI.10 algorithm:

  1. sort-key (lexicographic, entries without sort-key come last)
  2. Machine ID grouping
  3. version (version-aware comparison, where 6.19.9 > 6.17.1)
  4. Failed boot-count entries sorted to the bottom

GRUB Variable Stripping

BLS entries written by GRUB may contain $kernelopts or ${variable} syntax in the options field. LamBoot strips these and falls back to /proc/cmdline (via the installer) for the actual kernel command line.

See Also

← All documentation