Merge pull request #40 from edera-dev/chore/release-v0.0.26

chore(release): sprout: version 0.0.26

.github/workflows/ci-actions.yml

@@ -35,7 +35,7 @@ jobs:
         persist-credentials: false
 
     - name: setup uv
-      uses: astral-sh/setup-uv@2ddd2b9cb38ad8efd50337e8ab201519a34c9f24 # v7.1.1
+      uses: astral-sh/setup-uv@85856786d1ce8acfbcc2f13a5f3fbd6b938f9f41 # v7.1.2
 
     - name: zizmor
       run: uvx zizmor --pedantic --format sarif . > results.sarif
@@ -43,7 +43,7 @@ jobs:
         GH_TOKEN: "${{ secrets.GITHUB_TOKEN }}"
 
     - name: upload
-      uses: github/codeql-action/upload-sarif@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+      uses: github/codeql-action/upload-sarif@0499de31b99561a6d14a36a5f662c2a54f91beee # v4.31.2
       with:
         sarif_file: results.sarif
         category: zizmor

.github/workflows/codeql.yml

@@ -47,13 +47,13 @@ jobs:
         persist-credentials: false
 
     - name: initialize codeql
-      uses: github/codeql-action/init@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+      uses: github/codeql-action/init@0499de31b99561a6d14a36a5f662c2a54f91beee # v4.31.2
       with:
         languages: ${{ matrix.language }}
         build-mode: ${{ matrix.build-mode }}
         config-file: ./.github/codeql/codeql-config.yaml
 
     - name: perform codeql analysis
-      uses: github/codeql-action/analyze@4e94bd11f71e507f7f87df81788dff88d1dacbfb # v4.31.0
+      uses: github/codeql-action/analyze@0499de31b99561a6d14a36a5f662c2a54f91beee # v4.31.2
       with:
         category: "/language:${{matrix.language}}"

Cargo.lock

@@ -46,9 +46,9 @@ dependencies = [
 
 [[package]]
 name = "crypto-common"
-version = "0.1.6"
+version = "0.1.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1bfb12502f3fc46cca1bb51ac28df9d618d813cdc3d2f25b9fe775a34af26bb3"
+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
 dependencies = [
  "generic-array",
  "typenum",
@@ -66,13 +66,14 @@ dependencies = [
 
 [[package]]
 name = "edera-sprout-boot"
-version = "0.0.24"
+version = "0.0.26"
 dependencies = [
  "anyhow",
  "edera-sprout-build",
  "edera-sprout-config",
  "edera-sprout-eficore",
  "hex",
+ "jaarg",
  "log",
  "sha2",
  "toml",
@@ -82,18 +83,18 @@ dependencies = [
 
 [[package]]
 name = "edera-sprout-build"
-version = "0.0.24"
+version = "0.0.26"
 
 [[package]]
 name = "edera-sprout-config"
-version = "0.0.24"
+version = "0.0.26"
 dependencies = [
  "serde",
 ]
 
 [[package]]
 name = "edera-sprout-eficore"
-version = "0.0.24"
+version = "0.0.26"
 dependencies = [
  "anyhow",
  "bitflags",
@@ -106,9 +107,9 @@ dependencies = [
 
 [[package]]
 name = "generic-array"
-version = "0.14.9"
+version = "0.14.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "4bb6743198531e02858aeaea5398fcc883e71851fcbcb5a2f773e2fb6cb1edf2"
+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
 dependencies = [
  "typenum",
  "version_check",
@@ -120,6 +121,12 @@ version = "0.4.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
+[[package]]
+name = "jaarg"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8b216e5405f7e759ee0d16007f9d5c3346f9803a2e86cf01fc8df8baac43d0fa"
+
 [[package]]
 name = "libc"
 version = "0.2.177"
@@ -172,9 +179,9 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.41"
+version = "1.0.42"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ce25767e7b499d1b604768e7cde645d14cc8584231ea6b295e9c9eb22c02e1d1"
+checksum = "a338cc41d27e6cc6dce6cefc13a0729dfbb81c262b1f519331575dd80ef3067f"
 dependencies = [
  "proc-macro2",
 ]
@@ -252,9 +259,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.108"
+version = "2.0.110"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "da58917d35242480a05c2897064da0a80589a2a0476c9a3f2fdc83b53502e917"
+checksum = "a99801b5bd34ede4cf3fc688c5919368fea4e4814a4664359503e6015b280aea"
 dependencies = [
  "proc-macro2",
  "quote",

Cargo.toml

@@ -9,7 +9,7 @@ resolver = "3"
 
 [workspace.package]
 license = "Apache-2.0"
-version = "0.0.24"
+version = "0.0.26"
 homepage = "https://sprout.edera.dev"
 repository = "https://github.com/edera-dev/sprout"
 edition = "2024"
@@ -29,6 +29,11 @@ version = "0.4.3"
 default-features = false
 features = ["alloc"]
 
+[workspace.dependencies.jaarg]
+version = "0.2.1"
+default-features = false
+features = ["alloc"]
+
 [workspace.dependencies.serde]
 version = "1.0.228"
 default-features = false

Dockerfile

@@ -2,7 +2,7 @@
 ARG RUST_PROFILE=release
 ARG RUST_TARGET_SUBDIR=release
 
-FROM --platform=$BUILDPLATFORM rust:1.91.0-alpine@sha256:a3e3d30122c08c0ed85dcd8867d956f066be23c32ed67a0453bc04ce478ad69b AS build
+FROM --platform=$BUILDPLATFORM rust:1.91.1-alpine@sha256:fbcca3e30e26f79986809d5dbfcdbeaaf8d3f8a4475b7a19a973363b45c74d97 AS build
 RUN apk --no-cache add musl-dev busybox-static
 ARG RUST_PROFILE
 RUN adduser -S -s /bin/sh build

README.md

@@ -47,8 +47,9 @@ We recommend running Sprout without Secure Boot for development, and with Secure
 
 | Operating System | Secure Boot Enabled | Link                                                  |
 |------------------|---------------------|-------------------------------------------------------|
-| Ubuntu           | ✅                   | [Setup Guide](./docs/setup/signed/ubuntu.md)          |
+| Fedora           | ✅                   | [Setup Guide](./docs/setup/signed/fedora.md)          |
 | Debian           | ✅                   | [Setup Guide](./docs/setup/signed/debian.md)          |
+| Ubuntu           | ✅                   | [Setup Guide](./docs/setup/signed/ubuntu.md)          |
 | openSUSE         | ✅                   | [Setup Guide](./docs/setup/signed/opensuse.md)        |
 | Fedora           | ❌                   | [Setup Guide](./docs/setup/unsigned/fedora.md)        |
 | Alpine Edge      | ❌                   | [Setup Guide](./docs/setup/unsigned/alpine-edge.md)   |

crates/boot/Cargo.toml

@@ -12,6 +12,7 @@ anyhow.workspace = true
 edera-sprout-config.path = "../config"
 edera-sprout-eficore.path = "../eficore"
 hex.workspace = true
+jaarg.workspace = true
 sha2.workspace = true
 toml.workspace = true
 log.workspace = true

crates/boot/src/autoconfigure/linux.rs

@@ -25,7 +25,7 @@ const LINUX_CHAINLOAD_ACTION_PREFIX: &str = "linux-chainload-";
 const SCAN_LOCATIONS: &[&str] = &["\\boot", "\\"];
 
 /// Prefixes of kernel files to scan for.
-const KERNEL_PREFIXES: &[&str] = &["vmlinuz"];
+const KERNEL_PREFIXES: &[&str] = &["vmlinuz", "Image"];
 
 /// Prefixes of initramfs files to match to.
 const INITRAMFS_PREFIXES: &[&str] = &["initramfs", "initrd", "initrd.img"];

crates/boot/src/entries.rs

@@ -93,7 +93,17 @@ impl BootableEntry {
     }
 
     /// Determine if this entry matches `needle` by comparing to the name or title of the entry.
+    /// If `needle` ends with *, we will match a partial match.
     pub fn is_match(&self, needle: &str) -> bool {
+        // If the needle ends with '*', we will accept a partial match.
+        if needle.ends_with("*") {
+            // Strip off any '*' at the end.
+            let partial = needle.trim_end_matches("*");
+            // Check if the name or title start with the partial match.
+            return self.name.starts_with(partial) || self.title.starts_with(partial);
+        }
+
+        // Standard quality matching rules.
         self.name == needle || self.title == needle
     }
 

crates/boot/src/main.rs

@@ -6,7 +6,6 @@ extern crate alloc;
 use crate::context::{RootContext, SproutContext};
 use crate::entries::BootableEntry;
 use crate::options::SproutOptions;
-use crate::options::parser::OptionsRepresentable;
 use crate::phases::phase;
 use alloc::collections::BTreeMap;
 use alloc::format;
@@ -385,7 +384,7 @@ fn efi_main() -> Status {
     let result = run();
     if let Err(ref error) = result {
         // Print an error trace.
-        error!("sprout encountered an error:");
+        error!("sprout encountered an error: {}", error);
         for (index, stack) in error.chain().enumerate() {
             error!("[{}]: {}", index, stack);
         }

crates/boot/src/options.rs

@@ -1,10 +1,13 @@
-use crate::options::parser::{OptionDescription, OptionForm, OptionsRepresentable};
-use alloc::collections::BTreeMap;
 use alloc::string::{String, ToString};
 use anyhow::{Context, Result, bail};
-
-/// The Sprout options parser.
-pub mod parser;
+use core::ptr::null_mut;
+use jaarg::alloc::ParseMapResult;
+use jaarg::{
+    ErrorUsageWriter, ErrorUsageWriterContext, HelpWriter, HelpWriterContext, Opt, Opts,
+    StandardErrorUsageWriter, StandardFullHelpWriter,
+};
+use log::{error, info};
+use uefi_raw::Status;
 
 /// Default configuration file path.
 const DEFAULT_CONFIG_PATH: &str = "\\sprout.toml";
@@ -38,65 +41,61 @@ impl Default for SproutOptions {
 }
 
 /// The options parser mechanism for Sprout.
-impl OptionsRepresentable for SproutOptions {
-    /// Produce the [SproutOptions] structure.
-    type Output = Self;
+impl SproutOptions {
+    /// Produces [SproutOptions] from the arguments provided by the UEFI core.
+    /// Internally we utilize the `jaarg` argument parser which has excellent no_std support.
+    pub fn parse() -> Result<Self> {
+        // All the options for the Sprout executable.
+        const OPTIONS: Opts<&str> = Opts::new(&[
+            Opt::help_flag("help", &["--help"]).help_text("Display Sprout Help"),
+            Opt::flag("autoconfigure", &["--autoconfigure"])
+                .help_text("Enable Sprout autoconfiguration"),
+            Opt::value("config", &["--config"], "PATH")
+                .help_text("Path to Sprout configuration file"),
+            Opt::value("boot", &["--boot"], "ENTRY").help_text("Entry to boot, bypassing the menu"),
+            Opt::flag("force-menu", &["--force-menu"]).help_text("Force showing the boot menu"),
+            Opt::value("menu-timeout", &["--menu-timeout"], "TIMEOUT")
+                .help_text("Boot menu timeout, in seconds"),
+        ]);
 
-    /// All the Sprout options that are defined.
-    fn options() -> &'static [(&'static str, OptionDescription<'static>)] {
-        &[
-            (
-                "autoconfigure",
-                OptionDescription {
-                    description: "Enable Sprout Autoconfiguration",
-                    form: OptionForm::Flag,
-                },
-            ),
-            (
-                "config",
-                OptionDescription {
-                    description: "Path to Sprout configuration file",
-                    form: OptionForm::Value,
-                },
-            ),
-            (
-                "boot",
-                OptionDescription {
-                    description: "Entry to boot, bypassing the menu",
-                    form: OptionForm::Value,
-                },
-            ),
-            (
-                "force-menu",
-                OptionDescription {
-                    description: "Force showing of the boot menu",
-                    form: OptionForm::Flag,
-                },
-            ),
-            (
-                "menu-timeout",
-                OptionDescription {
-                    description: "Boot menu timeout, in seconds",
-                    form: OptionForm::Value,
-                },
-            ),
-            (
-                "help",
-                OptionDescription {
-                    description: "Display Sprout Help",
-                    form: OptionForm::Help,
-                },
-            ),
-        ]
-    }
+        // Acquire the arguments as determined by the UEFI core.
+        let args = eficore::env::args()?;
+
+        // Parse the OPTIONS into a map using jaarg.
+        let parsed = match OPTIONS.parse_map(
+            "sprout",
+            args.iter(),
+            |program_name| {
+                let ctx = HelpWriterContext {
+                    options: &OPTIONS,
+                    program_name,
+                };
+                info!("{}", StandardFullHelpWriter::new(ctx));
+            },
+            |program_name, error| {
+                let ctx = ErrorUsageWriterContext {
+                    options: &OPTIONS,
+                    program_name,
+                    error,
+                };
+                error!("{}", StandardErrorUsageWriter::new(ctx));
+            },
+        ) {
+            ParseMapResult::Map(map) => map,
+            ParseMapResult::ExitSuccess => unsafe {
+                uefi::boot::exit(uefi::boot::image_handle(), Status::SUCCESS, 0, null_mut());
+            },
+
+            ParseMapResult::ExitFailure => unsafe {
+                uefi::boot::exit(uefi::boot::image_handle(), Status::ABORTED, 0, null_mut());
+            },
+        };
 
-    /// Produces [SproutOptions] from the parsed raw `options` map.
-    fn produce(options: BTreeMap<String, Option<String>>) -> Result<Self> {
         // Use the default value of sprout options and have the raw options be parsed into it.
         let mut result = Self::default();
 
-        for (key, value) in options {
-            match key.as_str() {
+        for (key, value) in parsed {
+            match key {
                 "autoconfigure" => {
                     // Enable autoconfiguration.
                     result.autoconfigure = true;
@@ -104,12 +103,12 @@ impl OptionsRepresentable for SproutOptions {
 
                 "config" => {
                     // The configuration file to load.
-                    result.config = value.context("--config option requires a value")?;
+                    result.config = value;
                 }
 
                 "boot" => {
                     // The entry to boot.
-                    result.boot = Some(value.context("--boot option requires a value")?);
+                    result.boot = Some(value);
                 }
 
                 "force-menu" => {
@@ -119,7 +118,6 @@ impl OptionsRepresentable for SproutOptions {
 
                 "menu-timeout" => {
                     // The timeout for the boot menu in seconds.
-                    let value = value.context("--menu-timeout option requires a value")?;
                     let value = value
                         .parse::<u64>()
                         .context("menu-timeout must be a number")?;

crates/boot/src/options/parser.rs

@@ -1,153 +0,0 @@
-use alloc::collections::BTreeMap;
-use alloc::string::{String, ToString};
-use anyhow::{Context, Result, bail};
-use core::ptr::null_mut;
-use eficore::env;
-use log::info;
-use uefi_raw::Status;
-
-/// The type of option. This disambiguates different behavior
-/// of how options are handled.
-#[derive(Debug, Clone, Ord, PartialOrd, Eq, PartialEq)]
-pub enum OptionForm {
-    /// A flag, like --verbose.
-    Flag,
-    /// A value, in the form --abc 123 or --abc=123.
-    Value,
-    /// Help flag, like --help.
-    Help,
-}
-
-/// The description of an option, used in the option parser
-/// to make decisions about how to progress.
-#[derive(Debug, Clone)]
-pub struct OptionDescription<'a> {
-    /// The description of the option.
-    pub description: &'a str,
-    /// The type of option to parse as.
-    pub form: OptionForm,
-}
-
-/// Represents a type that can be parsed from command line arguments.
-/// This is a super minimal options parser mechanism just for Sprout.
-pub trait OptionsRepresentable {
-    /// The output type that parsing will produce.
-    type Output;
-
-    /// The configured options for this type. This should describe all the options
-    /// that are valid to produce the type. The left-hand side is the name of the option,
-    /// and the right-hand side is the description.
-    fn options() -> &'static [(&'static str, OptionDescription<'static>)];
-
-    /// Produces the type by taking the `options` and processing it into the output.
-    fn produce(options: BTreeMap<String, Option<String>>) -> Result<Self::Output>;
-
-    /// For minimalism, we don't want a full argument parser. Instead, we use
-    /// a simple --xyz = xyz: None and --abc 123 = abc: Some("123") format.
-    /// We also support the format: --abc=123
-    fn parse_raw() -> Result<BTreeMap<String, Option<String>>> {
-        // Access the configured options for this type.
-        let configured: BTreeMap<_, _> = BTreeMap::from_iter(Self::options().to_vec());
-
-        // Collect all the arguments to Sprout.
-        // Skip the first argument, which is the path to our executable.
-        let args = env::args()?;
-
-        // Represent options as key-value pairs.
-        let mut options = BTreeMap::new();
-
-        // Iterators makes this way easier.
-        let mut iterator = args.into_iter().peekable();
-
-        loop {
-            // Consume the next option, if any.
-            let Some(option) = iterator.next() else {
-                break;
-            };
-
-            // If the option doesn't start with --, that is invalid.
-            if !option.starts_with("--") {
-                bail!("invalid option: {option}");
-            }
-
-            // Strip the -- prefix off.
-            let mut option = option["--".len()..].trim().to_string();
-
-            // An optional value.
-            let mut value = None;
-
-            // Check if the option is of the form --abc=123
-            if let Some((part_key, part_value)) = option.split_once('=') {
-                let part_key = part_key.to_string();
-                let part_value = part_value.to_string();
-                option = part_key;
-                value = Some(part_value);
-            }
-
-            // Error on empty option names.
-            if option.is_empty() {
-                bail!("invalid empty option");
-            }
-
-            // Find the description of the configured option, if any.
-            let Some(description) = configured.get(option.as_str()) else {
-                bail!("invalid option: --{option}");
-            };
-
-            // Check if the option requires a value and error if none was provided.
-            if description.form == OptionForm::Value && value.is_none() {
-                // Check for the next value.
-                let maybe_next = iterator.peek();
-
-                // If the next value isn't another option, set the value to the next value.
-                // Otherwise, it is None.
-                value = if let Some(next) = maybe_next
-                    && !next.starts_with("--")
-                {
-                    iterator.next()
-                } else {
-                    None
-                };
-            }
-
-            // If the option form does not support a value and there is a value, error.
-            if description.form != OptionForm::Value && value.is_some() {
-                bail!("option --{} does not take a value", option);
-            }
-
-            // Handle the --help flag case.
-            if description.form == OptionForm::Help {
-                // Generic configured options output.
-                info!("Configured Options:");
-                for (name, description) in &configured {
-                    info!(
-                        "  --{}{}: {}",
-                        name,
-                        if description.form == OptionForm::Value {
-                            " <value>"
-                        } else {
-                            ""
-                        },
-                        description.description
-                    );
-                }
-                // Exit because the help has been displayed.
-                unsafe {
-                    uefi::boot::exit(uefi::boot::image_handle(), Status::SUCCESS, 0, null_mut());
-                };
-            }
-
-            // Insert the option and the value into the map.
-            options.insert(option, value);
-        }
-        Ok(options)
-    }
-
-    /// Parses the program arguments as a [Self::Output], calling [Self::parse_raw] and [Self::produce].
-    fn parse() -> Result<Self::Output> {
-        // Parse the program arguments into a raw map.
-        let options = Self::parse_raw().context("unable to parse options")?;
-        // Produce the options from the map.
-        Self::produce(options)
-    }
-}

crates/config/src/lib.rs

@@ -78,8 +78,7 @@ pub struct RootConfiguration {
 /// Options configuration for Sprout, used when the corresponding options are not specified.
 #[derive(Serialize, Deserialize, Debug, Default, Clone)]
 pub struct OptionsConfiguration {
-    /// The entry to boot without showing the boot menu.
-    /// If not specified, a boot menu is shown.
+    /// The entry to mark as the default entry, instead of the first entry.
     #[serde(rename = "default-entry", default)]
     pub default_entry: Option<String>,
     /// The timeout of the boot menu.

docs/setup/signed/debian.md

@@ -60,7 +60,7 @@ Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.e
 ## Step 4: Sign Sprout for Secure Boot
 
 ```bash
-# For x86_64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call.
+# For x86_64, sign the unsigned Sprout artifact and name it grubx64.efi which is what the shim will call.
 $ sbsign \
     --key /etc/sprout/secure-boot/mok.key \
     --cert /etc/sprout/secure-boot/mok.crt \
@@ -120,8 +120,8 @@ path = "\\EFI\\sprout\\ext4.efi"
 
 # global options.
 [options]
-# enable autoconfiguration by detecting bls enabled
-# filesystems and generating boot entries for them.
+# enable autoconfiguration by detecting installed kernels
+# generating boot entries for them.
 autoconfigure = true
 ```
 
@@ -130,14 +130,16 @@ If you do not have any drivers, exclude the drivers section entirely.
 
 ## Step 7: Configure Sprout Boot Entry
 
-In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
+In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
+and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
+`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
 
 ```bash
 # For x86_64, run this command to add Sprout as the default boot entry.
-$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
 
 # For aarch64, run this command to add Sprout as the default boot entry.
-$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
 ```
 
 Reboot your machine and it should boot into Sprout.

docs/setup/signed/fedora.md

@@ -0,0 +1,172 @@
+# Setup Sprout for Fedora with Secure Boot
+
+## Prerequisites
+
+- Modern Fedora release: tested on Fedora 43 x86_64.
+- EFI System Partition mounted on `/boot/efi` (the default)
+- You will need the following packages installed: `openssl`, `mokutil`, `sbsigntools`, `efibootmgr`
+
+**NOTE**: Fedora on ARM64 itself does not support Secure Boot consistently.
+
+## Step 1: Generate and Install Secure Boot Key
+
+```bash
+# Create a directory to store the Secure Boot MOK key and certificates.
+$ mkdir -p /etc/sprout/secure-boot
+# Change to the created directory.
+$ cd /etc/sprout/secure-boot
+# Generate a MOK key and certificate.
+$ openssl req \
+    -newkey rsa:4096 -nodes -keyout mok.key \
+    -new -x509 -sha256 -days 3650 -subj '/CN=Sprout Secure Boot/' \
+    -out mok.crt
+# Generate a DER encoded certificate for enrollment.
+$ openssl x509 -outform DER -in mok.crt -out mok.cer
+# Import the certificate into the Secure Boot environment.
+# This will ask you to make a password that will be used during enrollment.
+$ mokutil --import mok.cer
+# Reboot your machine.
+# During boot, MOK enrollment should appear. If it doesn't, ensure you are booting into the shim.
+# Press any key to begin MOK management. Select "Enroll MOK".
+# Select "View key 0", and ensure the subject says "CN=Sprout Secure Boot".
+# If the subject does not match, something has gone wrong with MOK enrollment.
+# Press Enter to continue, then select the "Continue" option.
+# When it asks to enroll the key, select the "Yes" option.
+# Enter the password that you created during the mokutil --import step.
+# Select "Reboot" to boot back into your Operating System.
+```
+
+## Step 2: Prepare the Secure Boot Environment
+
+```bash
+# Create a directory for Sprout EFI artifacts.
+$ mkdir -p /boot/efi/EFI/sprout
+
+# For x86_64, copy the following artifacts to the Sprout EFI directory.
+$ cp /boot/efi/EFI/fedora/shimx64.efi /boot/efi/EFI/sprout/shimx64.efi
+$ cp /boot/efi/EFI/fedora/mmx64.efi /boot/efi/EFI/sprout/mmx64.efi
+
+# For aarch64, copy the following artifacts to the Sprout EFI directory.
+$ cp /boot/efi/EFI/fedora/shimaa64.efi /boot/efi/EFI/sprout/shimaa64.efi
+$ cp /boot/efi/EFI/fedora/mmaa64.efi /boot/efi/EFI/sprout/mmaa64.efi
+```
+
+## Step 3: Install Unsigned Sprout
+
+Download the latest sprout.efi release from the [GitHub releases page](https://github.com/edera-dev/sprout/releases).
+For x86_64 systems, download the `sprout-x86_64.efi` file, and for ARM64 systems, download the `sprout-aarch64.efi` file.
+Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.efi` on your EFI System Partition.
+
+## Step 4: Sign Sprout for Secure Boot
+
+```bash
+# For x86_64, sign the unsigned Sprout artifact and name it grubx64.efi which is what the shim will call.
+$ sbsign \
+    --key /etc/sprout/secure-boot/mok.key \
+    --cert /etc/sprout/secure-boot/mok.crt \
+    --output /boot/efi/EFI/sprout/grubx64.efi \
+    /boot/efi/EFI/sprout/sprout.unsigned.efi
+
+# For aarch64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call.
+$ sbsign \
+    --key /etc/sprout/secure-boot/mok.key \
+    --cert /etc/sprout/secure-boot/mok.crt \
+    --output /boot/efi/EFI/sprout/grubaa64.efi \
+    /boot/efi/EFI/sprout/sprout.unsigned.efi
+```
+
+## Step 5: Install and Sign EFI Drivers
+
+You will need a filesystem EFI driver if `/boot` is not FAT32 or ExFAT.
+
+### ext4
+
+Most Fedora systems use an ext4 filesystem for `/boot`, if that is the case, use the ext4 instructions here:
+
+Install the necessary `edk2-ext4` package:
+
+```bash
+# Install the ext4 driver from the package manager.
+$ dnf install edk2-ext4
+```
+
+Copy the ext4 driver to `/boot/efi/EFI/sprout/ext4.unsigned.efi`:
+
+```bash
+# For x86_64, copy the ext4x64.efi driver to the Sprout EFI directory.
+$ cp /usr/share/edk2/drivers/ext4x64.efi /boot/efi/EFI/sprout/ext4.unsigned.efi
+
+# For aarch64, copy the ext4aa64.efi driver to the Sprout EFI directory.
+$ cp /usr/share/edk2/drivers/ext4aa64.efi /boot/efi/EFI/sprout/ext4.unsigned.efi
+```
+
+```bash
+# Sign the ext4 driver at ext4.unsigned.efi, placing it at ext4.efi, which will be used in the configuration.
+$ sbsign \
+    --key /etc/sprout/secure-boot/mok.key \
+    --cert /etc/sprout/secure-boot/mok.crt \
+    --output /boot/efi/EFI/sprout/ext4.efi \
+    /boot/efi/EFI/sprout/ext4.unsigned.efi
+```
+
+### Other Filesystems
+
+If you need another driver, you can download EFI filesystem drivers from [EfiFs releases](https://github.com/pbatard/EfiFs/releases).
+Copy the driver to `/boot/efi/EFI/sprout/DRIVER_NAME.unsigned.efi` for signing, then sign it like this:
+
+```bash
+# Sign your driver, placing it at DRIVER_NAME.efi, which will be used in the configuration.
+$ sbsign \
+    --key /etc/sprout/secure-boot/mok.key \
+    --cert /etc/sprout/secure-boot/mok.crt \
+    --output /boot/efi/EFI/sprout/DRIVER_NAME.efi \
+    /boot/efi/EFI/sprout/DRIVER_NAME.unsigned.efi
+```
+
+You will add the driver in your Sprout configuration below, like this:
+
+```toml
+[drivers.DRIVER_NAME]
+path = "\\EFI\\sprout\\DRIVER_NAME.efi"
+```
+
+## Step 6: Create Sprout Configuration
+
+Write the following to the file `/boot/efi/sprout.toml`:
+
+```toml
+# sprout configuration: version 1
+version = 1
+
+# load an ext4 EFI driver.
+# skip this if you do not have a filesystem driver.
+# if your filesystem driver is not named ext4, change accordingly.
+[drivers.ext4]
+path = "\\EFI\\sprout\\ext4.efi"
+
+# global options.
+[options]
+# enable autoconfiguration by detecting bls enabled
+# filesystems and generating boot entries for them.
+autoconfigure = true
+```
+
+Ensure you add the signed driver paths to the configuration, not the unsigned ones.
+If you do not have any drivers, exclude the drivers section entirely.
+
+## Step 7: Configure Sprout Boot Entry
+
+In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
+and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
+`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
+
+```bash
+# For x86_64, run this command to add Sprout as the default boot entry.
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
+
+# For aarch64, run this command to add Sprout as the default boot entry.
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
+```
+
+Reboot your machine and it should boot into Sprout.
+If Sprout fails to boot, it should boot into the original bootloader.

docs/setup/signed/opensuse.md

@@ -128,11 +128,13 @@ If you do not have any drivers, exclude the drivers section entirely.
 
 ## Step 7: Configure Sprout Boot Entry
 
-In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
+In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
+and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
+`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
 
 ```bash
 # Run this command to add Sprout as the default boot entry.
-$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shim.efi'
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shim.efi'
 ```
 
 Reboot your machine and it should boot into Sprout.

docs/setup/signed/ubuntu.md

@@ -59,7 +59,7 @@ Copy the downloaded `sprout.efi` file to `/boot/efi/EFI/sprout/sprout.unsigned.e
 ## Step 4: Sign Sprout for Secure Boot
 
 ```bash
-# For x86_64, sign the unsigned Sprout artifact and name it grubaa64.efi which is what the shim will call.
+# For x86_64, sign the unsigned Sprout artifact and name it grubx64.efi which is what the shim will call.
 $ sbsign \
     --key /etc/sprout/secure-boot/mok.key \
     --cert /etc/sprout/secure-boot/mok.crt \
@@ -119,8 +119,8 @@ path = "\\EFI\\sprout\\ext4.efi"
 
 # global options.
 [options]
-# enable autoconfiguration by detecting bls enabled
-# filesystems and generating boot entries for them.
+# enable autoconfiguration by detecting installed kernels
+# generating boot entries for them.
 autoconfigure = true
 ```
 
@@ -129,14 +129,18 @@ If you do not have any drivers, exclude the drivers section entirely.
 
 ## Step 7: Configure Sprout Boot Entry
 
-In the following commands, replace /dev/ESP_PARTITION with the actual path to the ESP partition block device.
+## Step 7: Configure Sprout Boot Entry
+
+In the following commands, replace /dev/BLOCK_DEVICE with the device that houses your GPT partition table,
+and PARTITION_NUMBER with the partition number of the EFI System Partition. For example, if your EFI System Partition is
+`/dev/sda1`, the BLOCK_DEVICE would be `/dev/sda` and the PARTITION_NUMBER would be `1`
 
 ```bash
 # For x86_64, run this command to add Sprout as the default boot entry.
-$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimx64.efi'
 
 # For aarch64, run this command to add Sprout as the default boot entry.
-$ efibootmgr -d /dev/ESP_PARTITION -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
+$ efibootmgr -d /dev/BLOCK_DEVICE -p PARTITION_NUMBER -c -L 'Sprout' -l '\EFI\sprout\shimaa64.efi'
 ```
 
 Reboot your machine and it should boot into Sprout.

hack/dev/boot.sh

@@ -30,9 +30,9 @@ if [ "${QEMU_GDB_WAIT}" = "1" ]; then
 	set -- "${@}" "-S"
 fi
 
-set -- "${@}" -smp 2 -m 4096
+set -- "${@}" -nodefaults -smp 2 -m 4096
 
-if [ "${NO_GRAPHICAL_BOOT}" = "1" ]; then
+if [ "${NO_GRAPHICAL}" = "1" ]; then
 	set -- "${@}" -nographic
 else
 	if [ "${GRAPHICAL_ONLY}" != "1" ]; then
@@ -41,7 +41,7 @@ else
 		else
 			set -- "${@}" \
 				-device virtio-serial-pci,id=vs0 \
-				-chardev stdio,id=stdio0 \
+				-chardev stdio,id=stdio0,signal=off \
 				-device virtconsole,chardev=stdio0,id=console0
 		fi
 	fi
@@ -62,6 +62,12 @@ if [ "${NO_INPUT}" != "1" ]; then
 		-device usb-mouse
 fi
 
+if [ "${NO_NETWORK}" != "1" ]; then
+	set -- "${@}" \
+		-netdev user,id=network0 \
+		-device virtio-net-pci,netdev=network0
+fi
+
 rm -f "${FINAL_DIR}/ovmf-boot.fd"
 cp "${FINAL_DIR}/ovmf.fd" "${FINAL_DIR}/ovmf-boot.fd"
 if [ "${TARGET_ARCH}" = "aarch64" ]; then

hack/dev/boot/Dockerfile

@@ -1,4 +1,4 @@
-FROM --platform=$BUILDPLATFORM debian:trixie@sha256:fd8f5a1df07b5195613e4b9a0b6a947d3772a151b81975db27d47f093f60c6e6 AS build
+FROM --platform=$BUILDPLATFORM debian:trixie@sha256:01a723bf5bfb21b9dda0c9a33e0538106e4d02cce8f557e118dd61259553d598 AS build
 ARG BUILDPLATFORM
 ARG EFI_NAME
 RUN export DEBIAN_FRONTEND=noninteractive && apt-get update && apt-get install -y \

hack/dev/build.sh

@@ -48,7 +48,7 @@ copy_from_image_polyfill() {
 	SOURCE="${2}"
 	TARGET="${3}"
 
-	docker build -t "${IMAGE}-copy-polyfill:${DOCKER_TAG}" --build-arg "TARGET_IMAGE=${IMAGE}:${DOCKER_TAG}" \
+	docker build --platform="${DOCKER_TARGET}" -t "${IMAGE}-copy-polyfill:${DOCKER_TAG}" --build-arg "TARGET_IMAGE=${IMAGE}:${DOCKER_TAG}" \
 		-f hack/dev/utils/Dockerfile.copy-polyfill hack
 	# note: the -w '//' is a workaround for Git Bash where / is magically rewritten.
 	docker run --rm -i -w '//' "${IMAGE}-copy-polyfill:${DOCKER_TAG}" cat "image/${SOURCE}" >"${TARGET}"
@@ -81,7 +81,7 @@ if [ "${SKIP_VM_BUILD}" != "1" ]; then
 	copy_from_image "${DOCKER_PREFIX}/sprout-ovmf-${TARGET_ARCH}" "ovmf.fd" "${FINAL_DIR}/ovmf.fd"
 	copy_from_image "${DOCKER_PREFIX}/sprout-ovmf-${TARGET_ARCH}" "shell.efi" "${FINAL_DIR}/shell.efi"
 	docker build --platform="${DOCKER_TARGET}" -t "${DOCKER_PREFIX}/sprout-initramfs-${TARGET_ARCH}:${DOCKER_TAG}" \
-		-f hack/dev/vm/Dockerfile.initramfs "${FINAL_DIR}"
+		-f hack/dev/vm/Dockerfile.initramfs "hack/dev/vm"
 	copy_from_image "${DOCKER_PREFIX}/sprout-initramfs-${TARGET_ARCH}" "initramfs" "${FINAL_DIR}/initramfs"
 
 	if [ -n "${SPROUT_XEN_EFI_OVERRIDE}" ]; then

hack/dev/configs/all.sprout.toml

@@ -8,7 +8,7 @@ has-item = "\\vmlinuz"
 
 [actions.chainload-kernel]
 chainload.path = "$boot\\vmlinuz"
-chainload.options = ["console=hvc0"]
+chainload.options = ["console=hvc0", "overlaytmpfs=yes"]
 chainload.linux-initrd = "$boot\\initramfs"
 
 [entries.kernel]

hack/dev/configs/kernel.sprout.toml

@@ -9,7 +9,7 @@ has-item = "\\vmlinuz"
 
 [actions.chainload-kernel]
 chainload.path = "$boot\\vmlinuz"
-chainload.options = ["console=hvc0"]
+chainload.options = ["console=hvc0", "overlaytmpfs=yes"]
 chainload.linux-initrd = "$boot\\initramfs"
 
 [entries.kernel]

hack/dev/kernel/Dockerfile

@@ -1,7 +1,7 @@
-ARG KERNEL_SOURCE_URL=https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.17.2.tar.xz
-ARG KERNEL_CHECKSUM=sha256:fdebcb065065f5c1b8dc68a6fb59cda50cdddbf9103d207c2196d55ea764f57f
+ARG KERNEL_SOURCE_URL=https://cdn.kernel.org/pub/linux/kernel/v6.x/linux-6.17.8.tar.xz
+ARG KERNEL_CHECKSUM=sha256:5a8de64a75fca706c01c6c0a77cf75a74618439db195e25f1f0268af6b2fb1da
 
-FROM --platform=$BUILDPLATFORM debian:trixie@sha256:fd8f5a1df07b5195613e4b9a0b6a947d3772a151b81975db27d47f093f60c6e6 AS buildenv
+FROM --platform=$BUILDPLATFORM debian:trixie@sha256:01a723bf5bfb21b9dda0c9a33e0538106e4d02cce8f557e118dd61259553d598 AS buildenv
 RUN export DEBIAN_FRONTEND=noninteractive && apt-get update && apt-get install -y \
       build-essential squashfs-tools python3-yaml \
       patch diffutils sed mawk findutils zstd \

hack/dev/kernel/docker-build.sh

@@ -36,9 +36,14 @@ if [ "${TARGET_KARCH}" = "x86_64" ]; then
 fi
 make CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}" mod2yesconfig
 
+./scripts/config -e UEVENT_HELPER
+./scripts/config --set-str UEVENT_HELPER_PATH "/sbin/hotplug"
+
 ./scripts/config -e DRM_VIRTIO_GPU
 ./scripts/config -e FRAMEBUFFER_CONSOLE
 ./scripts/config -e FRAMEBUFFER_CONSOLE_DETECT_PRIMARY
+./scripts/config -e LOGO
+
 ./scripts/config -e XEN_DOM0
 
 make "-j$(nproc)" CROSS_COMPILE="${MAYBE_CROSS_COMPILE}" ARCH="${TARGET_KARCH}"

hack/dev/utils/Dockerfile.copy-direct

@@ -1 +1 @@
-FROM --platform=$BUILDPLATFORM debian:trixie@sha256:fd8f5a1df07b5195613e4b9a0b6a947d3772a151b81975db27d47f093f60c6e6
+FROM --platform=$BUILDPLATFORM debian:trixie@sha256:01a723bf5bfb21b9dda0c9a33e0538106e4d02cce8f557e118dd61259553d598

hack/dev/utils/Dockerfile.copy-polyfill

@@ -1,4 +1,4 @@
 ARG TARGET_IMAGE=scratch
 FROM ${TARGET_IMAGE} AS image
-FROM --platform=$BUILDPLATFORM debian:trixie@sha256:fd8f5a1df07b5195613e4b9a0b6a947d3772a151b81975db27d47f093f60c6e6 AS final
+FROM --platform=$BUILDPLATFORM debian:trixie@sha256:01a723bf5bfb21b9dda0c9a33e0538106e4d02cce8f557e118dd61259553d598 AS final
 COPY --from=image / /image

hack/dev/vm/Dockerfile.initramfs

@@ -1,5 +1,5 @@
-FROM alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1 AS rootfs
-RUN apk --no-cache add alpine-base tzdata
+FROM alpine:3.22@sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412 AS rootfs
+RUN apk --no-cache add alpine-base tzdata ifupdown-ng agetty
 RUN rc-update add devfs sysinit && \
     rc-update add dmesg sysinit && \
     rc-update add mdev sysinit && \
@@ -7,6 +7,7 @@ RUN rc-update add devfs sysinit && \
     rc-update add sysctl boot && \
     rc-update add hostname boot && \
     rc-update add bootmisc boot && \
+    rc-update add networking boot && \
     rc-update add syslog boot && \
     rc-update add mount-ro shutdown && \
     rc-update add killprocs shutdown && \
@@ -14,11 +15,12 @@ RUN rc-update add devfs sysinit && \
     ln -s /sbin/init /init && \
     echo 'root:root' | chpasswd && \
     echo 'sprout' > /etc/hostname && \
-    echo '' > /etc/motd && \
+    rm /etc/motd && \
     ln -s /usr/share/zoneinfo/UTC /etc/localtime && \
-    echo 'hvc0::respawn:/sbin/getty -L hvc0 115200 vt100' >> /etc/inittab
+    echo 'hvc0::respawn:/sbin/agetty --autologin root -L hvc0 115200 vt100' >> /etc/inittab
+COPY files/interfaces /etc/network/interfaces
 
-FROM alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1 AS build
+FROM alpine:3.22@sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412 AS build
 COPY --from=rootfs / /rootfs
 WORKDIR /rootfs
 RUN find . | cpio -R 0:0 --ignore-devno --renumber-inodes -o -H newc --quiet > /initramfs

hack/dev/vm/Dockerfile.ovmf

@@ -1,4 +1,4 @@
-FROM alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1 AS build
+FROM alpine:3.22@sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412 AS build
 ARG TARGETPLATFORM
 RUN if [ "${TARGETPLATFORM}" = "linux/amd64" ] || [ "${TARGETPLATFORM}" = "linux/x86_64" ]; then \
       apk --no-cache add ovmf edk2-shell; cp /usr/share/ovmf/bios.bin /ovmf.fd; fi

hack/dev/vm/Dockerfile.xen

@@ -1,4 +1,4 @@
-FROM alpine:3.22@sha256:4bcff63911fcb4448bd4fdacec207030997caf25e9bea4045fa6c8c44de311d1 AS build
+FROM alpine:3.22@sha256:4b7ce07002c69e8f3d704a9c5d6fd3053be500b7f1c69fc0d80990c2ad8dd412 AS build
 ARG TARGETPLATFORM
 RUN apk add --no-cache xen-hypervisor && cp /usr/lib/efi/xen.efi /xen.efi
 

hack/dev/vm/files/interfaces

@@ -0,0 +1,3 @@
+auto eth0
+iface eth0
+    use dhcp

rust-toolchain.toml

@@ -1,4 +1,4 @@
 [toolchain]
-channel = "1.91.0"
+channel = "1.91.1"
 components = ["rustfmt", "clippy"]
 targets = ["x86_64-unknown-uefi", "aarch64-unknown-uefi"]