efistubmgr

Minimal EFISTUB manager written in Rust. It creates and manages UEFI boot entries pointing directly at a Linux kernel EFI stub, bypassing external bootloaders. Designed for NixOS/finix setups where system rebuilds generate new kernel images on every run and you need deterministic boot entry management without parsing raw `efibootmgr` output. > [!NOTE] > `efistubmgr` is a primitive, low-level CLI tool, not a full bootloader framework. It solely manages NVRAM entries. You need to write your own orchestration script (with external bootloader hook) to copy kernels/initrds to the ESP, manage GC/pruning of old files, and trigger `efistubmgr`. ## Overview Interacting with `efibootmgr` via automation is brittle. `efistubmgr` embeds a custom timestamp inside the `optional_data` array of each UEFI entry it generates. This allows it to identify its own entries, maintain chronological sorting, and manage `BootOrder` programmatically. Entries created by other tools (Windows Boot Manager, shim, standard system entries) remain completely untouched. ## Features * `create` - Allocates a new `Boot####` entry on the target ESP, appends the cmdline and timestamp metadata, then prepends its ID to `BootOrder`. * `delete` - Removes the specified `Boot####` entry from NVRAM and cleans references in `BootOrder`. * `list` - Parses NVRAM and outputs `efistubmgr`-managed entries sorted newest-first. ## Output Format & Returns `efistubmgr` is designed to be easily parsed inside scripts: * `create` - Returns the assigned entry ID (`Boot####` without the `Boot` prefix, e.g. `0001`). * `list` - Returns lines formatted as ` ` (e.g. `0001 1787820063`), sorted newest-first. * `delete` - Returns nothing on success (exit status 0). ## Nix Flake Usage Add `efistubmgr` to your `flake.nix` inputs: ```nix inputs = { nixpkgs.url = "github:nixos/nixpkgs/nixos-unstable"; efistubmgr = { url = "github:FixeQD/efistubmgr"; inputs.nixpkgs.follows = "nixpkgs"; }; }; ``` Then expose the package via `overlays` in your system configuration: ```nix nixpkgs.overlays = [ (final: prev: { efistubmgr = efistubmgr.packages.${system}.default; }) ]; ``` ## Usage ```bash efistubmgr create [--timestamp ] efistubmgr delete efistubmgr list ``` Run `efistubmgr --help` for full flag descriptions. ## Example Integration Script
Click to view a complete NixOS/finix install hook script ```nix efistubHook = pkgs.writeShellScript "efistub-install" '' set -euo pipefail # ── Paths & metadata ────────────────────────────────────────────────────── BOOTSPEC="$1/boot.json" BOOT_DIR="${efiMount}/EFI/nixos" EFISTUBMGR="${pkgs.efistubmgr}/bin/efistubmgr" TIMESTAMP=$(${pkgs.coreutils}/bin/date +%s) HUMAN_DATE=$( ${pkgs.coreutils}/bin/date -d "@$TIMESTAMP" '+%Y-%m-%d %H:%M:%S %Z' ) KERNEL_PATH="$BOOT_DIR/kernel-$TIMESTAMP.efi" INITRD_PATH="$BOOT_DIR/initrd-$TIMESTAMP" # ── Helpers ─────────────────────────────────────────────────────────────── get_rev() { local target="$1" local path="$2" local link for link in /nix/var/nix/profiles/system-*-link; do [ -e "$link" ] || continue case "$(readlink "$link")" in "$target"|"$path") printf '%s\n' "$link" | ${pkgs.gnugrep}/bin/grep -oE 'system-[0-9]+-link' | ${pkgs.gnugrep}/bin/grep -oE '[0-9]+' | ${pkgs.gawk}/bin/awk '{print "rev. " $1}' return ;; esac done } is_kept_timestamp() { local needle="$1" for ts in "''${KEEP_TIMESTAMPS[@]}"; do [ "$ts" = "$needle" ] && return 0 done return 1 } is_seen_timestamp() { local needle="$1" for ts in "''${ORPHAN_TIMESTAMPS[@]}"; do [ "$ts" = "$needle" ] && return 0 done return 1 } # ── Validate & read bootspec ────────────────────────────────────────────── [ -r "$BOOTSPEC" ] || { echo "ERROR: boot.json not found at $BOOTSPEC"; exit 1; } [ -b "${bootDisk}" ] || { echo "ERROR: boot device not found: ${bootDisk}"; exit 1; } KERNEL=$(${pkgs.jq}/bin/jq -r '."org.nixos.bootspec.v1".kernel' "$BOOTSPEC") INITRD=$(${pkgs.jq}/bin/jq -r '."org.nixos.bootspec.v1".initrd' "$BOOTSPEC") INIT=$(${pkgs.jq}/bin/jq -r '."org.nixos.bootspec.v1".init' "$BOOTSPEC") PARAMS=$(${pkgs.jq}/bin/jq -r '."org.nixos.bootspec.v1".kernelParams | join(" ")' "$BOOTSPEC") LABEL=$(${pkgs.jq}/bin/jq -r '."org.nixos.bootspec.v1".label // empty' "$BOOTSPEC") TOPLEVEL=$(${pkgs.jq}/bin/jq -r '."org.nixos.bootspec.v1".toplevel // empty' "$BOOTSPEC") [ -z "$LABEL" ] || [ "$LABEL" = "null" ] && LABEL="Finix" [ -z "$TOPLEVEL" ] && TOPLEVEL="$1" REV=$(get_rev "$TOPLEVEL" "$1") DESCRIPTION="$LABEL''${REV:+ $REV} ❖ $HUMAN_DATE" # ── Install kernel & initrd ─────────────────────────────────────────────── mkdir -p "$BOOT_DIR" echo "==> Installing kernel and initrd (timestamp: $TIMESTAMP)" install -m 0644 "$KERNEL" "$KERNEL_PATH" install -m 0644 "$INITRD" "$INITRD_PATH" # ── Secure Boot ─────────────────────────────────────────────────────────── if [ -d /etc/secureboot/keys ]; then echo "==> sbctl: signing kernel" ${pkgs.sbctl}/bin/sbctl sign "$KERNEL_PATH" || \ echo "WARNING: sbctl signing failed, but continuing (Secure Boot may not work)" fi # ── Create NVRAM entry ──────────────────────────────────────────────────── echo "==> Creating new primary entry: $DESCRIPTION (timestamp $TIMESTAMP)" NEW_ID=$("$EFISTUBMGR" create "${efiMount}" \ '\EFI\nixos\kernel-'"$TIMESTAMP"'.efi' \ "$DESCRIPTION" \ "initrd=\EFI\nixos\initrd-$TIMESTAMP init=$INIT $PARAMS" \ --timestamp "$TIMESTAMP") echo "==> Created Boot$NEW_ID" # ── Keep newest generations ─────────────────────────────────────────────── mapfile -t GENERATIONS < <("$EFISTUBMGR" list) echo "==> ''${#GENERATIONS[@]} finix generation(s) in NVRAM" KEEP_TIMESTAMPS=() for line in "''${GENERATIONS[@]:0:${toString keepGenerations}}"; do KEEP_TIMESTAMPS+=( "$(${pkgs.gawk}/bin/awk '{print $2}' <<<"$line")" ) done declare -A PRUNE_IDS if [ "''${#GENERATIONS[@]}" -gt "${toString keepGenerations}" ]; then for line in "''${GENERATIONS[@]:${toString keepGenerations}}"; do id=$(${pkgs.gawk}/bin/awk '{print $1}' <<<"$line") ts=$(${pkgs.gawk}/bin/awk '{print $2}' <<<"$line") "$EFISTUBMGR" delete "$id" PRUNE_IDS["$ts"]="$id" done fi # ── Remove orphaned ESP files ───────────────────────────────────────────── ORPHAN_TIMESTAMPS=() for f in "$BOOT_DIR"/kernel-*.efi "$BOOT_DIR"/initrd-*; do [ -e "$f" ] || continue base=$(basename "$f") file_ts="''${base#*-}" file_ts="''${file_ts%.efi}" if ! is_kept_timestamp "$file_ts" && ! is_seen_timestamp "$file_ts"; then ORPHAN_TIMESTAMPS+=("$file_ts") fi done for ts in "''${ORPHAN_TIMESTAMPS[@]}"; do if [ -n "''${PRUNE_IDS[$ts]:-}" ]; then echo "==> Removing orphaned ESP files kernel-$ts.efi + initrd-$ts" \ "(ts $ts, removed matching Boot''${PRUNE_IDS[$ts]} NVRAM entry)" else echo "==> Removing orphaned ESP files kernel-$ts.efi + initrd-$ts" \ "(ts $ts, no matching NVRAM entry)" fi rm -f "$BOOT_DIR/kernel-$ts.efi" "$BOOT_DIR/initrd-$ts" done echo "==> EFISTUB setup complete" ''; ```
## Build ```bash nix build ``` Or via Cargo: ```bash cargo build --release ``` ## Technical Notes * Boot parameters are serialized in UTF-16LE encoding to align with Linux EFI stub parsing requirements. * Operations (`create`, `delete`, `list`) acquire an exclusive lock on `/run/efistubmgr.lock` to prevent race conditions during parallel nix rebuilds. * Direct NVRAM manipulation contains inherent risks. `delete` will remove any valid ID supplied to it, even if created externally. Validate target paths and arguments before execution. ## License GPL-3.0-only