WORKFLOW 1

BIOS/CSM to UEFI migration

Convert a legacy BIOS/CSM machine to native UEFI without reinstalling the OS. Estimated time: 15 to 30 minutes.

Before you begin

Have a bootable rescue medium ready (live USB or PXE).
Confirm your firmware has UEFI support (most machines since 2011 do).
Ensure your storage is GPT or has space for conversion. MBR disks are converted to GPT as part of this workflow.
lamboot-tools 0.9.1 must be installed. x86_64 or aarch64 only.

Step 1: Preflight check

Run the preflight check without making any changes. Review all output before proceeding.

Preflight

sudo lamboot-migrate preflight
# Exit 0 = ready. Exit 4 = safety check failed; review output.
# Exit 7 = missing prerequisites; install them first.

Step 2: Backup

Create an explicit pre-migration backup. lamboot-migrate creates one automatically, but a named backup makes recovery easier if the machine can't boot.

Create backup

sudo lamboot-backup save pre-migration
sudo lamboot-backup list          # Confirm backup appears

Step 3: Run the migration

Run migration

sudo lamboot-migrate to-uefi
# The tool will:
#   1. Create an additional backup
#   2. Add an ESP if none exists (or resize if < 512 MB)
#   3. Install the UEFI bootloader
#   4. Register NVRAM boot entries
#   5. Update /etc/fstab if needed
#   6. Print a summary and recommended next step

# Check exit code
rc=$?
case $rc in
    0) echo "Migration complete. Reboot when ready." ;;
    3) echo "Already UEFI - nothing to do." ;;
    4) echo "Safety check refused the migration. Review output." ;;
    *) echo "Migration failed ($rc). Do not reboot until resolved." ;;
esac

Step 4: Reboot and verify

Post-reboot verification

# After reboot, verify the system is running in UEFI mode
sudo lamboot-diagnose --json | jq '.summary.status'
# Expect: "pass" or "warn"

# Check firmware mode specifically
sudo lamboot-diagnose --category=nvram

Recovery: if the machine doesn't boot

Recovery from rescue environment

# Boot from a rescue medium with lamboot-tools installed
# Mount your root filesystem, then:
sudo lamboot-backup list
sudo lamboot-backup restore pre-migration

WORKFLOW 2

Diagnose and repair

Find and fix boot environment issues on any machine. The right workflow for routine health checks and targeted problem-solving.

Option A: Interactive guided session (recommended)

lamboot-doctor runs the full diagnostic, groups findings by priority, explains each issue, proposes fixes, and walks you through applying them.

Interactive doctor session

sudo lamboot-doctor run
# Doctor will:
#   1. Run lamboot-diagnose (all categories)
#   2. Group and explain findings by priority
#   3. For each actionable group, propose the right repair tool
#   4. Ask before applying any change
#   5. Re-run diagnose at the end and report the delta

Option B: Manual diagnose-then-repair

Run lamboot-diagnose first, review all findings, then apply targeted repairs.

Manual diagnose-then-repair

# 1. Full audit - shows all categories
sudo lamboot-diagnose

# 2. Review findings; focus on error/critical first
sudo lamboot-diagnose --min-severity warning

# 3. Get remediation commands for actionable findings
sudo lamboot-diagnose --json | \
    jq -r '.findings[] | select(.severity != "info") | "\(.id): \(.remediation.command)"'

# 4. Backup before applying any repair
sudo lamboot-backup save before-repair

# 5. Apply all safe automated repairs
sudo lamboot-repair run --dry-run   # Preview first
sudo lamboot-repair run

# 6. Re-diagnose to confirm
sudo lamboot-diagnose

Option C: Automated pipeline

For CI or unattended hosts, use --auto mode. The exit code drives the pipeline.

CI/automation pattern

sudo lamboot-diagnose --json --fail-on warning > /tmp/diag.json
rc=$?
if [[ $rc -ne 0 ]]; then
    sudo lamboot-backup save auto-repair-$(date +%Y%m%d)
    sudo lamboot-repair run --auto --yes
    # Re-diagnose; fail the pipeline if issues remain
    sudo lamboot-diagnose --json --fail-on error
fi

WORKFLOW 3

Secure Boot with Unified Kernel Images

Enroll custom Secure Boot keys and build a signed UKI that loads without a shim. Prerequisite: the machine must already be in native UEFI mode.

Who this is for: system administrators who want firmware-verified boot with their own signing key rather than distro keys. Not required for most use cases. Standard Secure Boot with shim and distro keys is a supported configuration that lamboot-diagnose will confirm as healthy.

Step 1: Generate signing keys

Generate keys

sudo lamboot-signing-keys generate \
    --org "Acme Corp" \
    --cn "Acme Boot Keys 2026"

# Keys are created at /etc/lamboot/keys/
# - platform.key (PK)
# - key-exchange.key (KEK)
# - signature-db.key (db)
# and their corresponding .crt and .cer counterparts

Step 2: Enter Setup Mode and enroll keys

Enroll keys

# Check current Secure Boot state
sudo lamboot-diagnose --category secureboot

# lamboot-signing-keys enroll requires Setup Mode
# Enter Setup Mode in firmware settings (clear PK), then:
sudo lamboot-signing-keys enroll

# The tool enrolls PK, KEK, and db in the correct order
# and writes the Secure Boot state after enrollment.

Step 3: Build and sign a UKI

Build UKI

# Build a UKI from the current running kernel
sudo lamboot-uki-build build

# Or specify a kernel version
sudo lamboot-uki-build build --kernel 6.8.12-amd64

# Verify the signature
sudo lamboot-uki-build verify /boot/efi/EFI/Linux/linux-6.8.12.efi

Step 4: Install to ESP and register boot entry

Install UKI

# Install the UKI to the ESP
sudo lamboot-uki-build install

# Verify it appears in NVRAM boot order
sudo lamboot-nvram list

# Final health check
sudo lamboot-diagnose

Step 5: Automate kernel updates

/etc/kernel/postinst.d/lamboot-uki

# /etc/kernel/postinst.d/90-lamboot-uki
#!/bin/sh
set -e
VERSION="$1"
sudo lamboot-uki-build build --kernel "$VERSION"
sudo lamboot-uki-build install --kernel "$VERSION"

Place this script in /etc/kernel/postinst.d/ and make it executable. On Debian/Ubuntu, the kernel package calls all hooks in that directory on every kernel install or upgrade, ensuring a signed UKI is installed and registered automatically.

Workflows