Crate iso_parser 

iso-parser

Boot entry discovery from ISO installation media. Scans directories for .iso files, detects distribution layouts (Arch, Debian/Ubuntu, Fedora, RHEL family, Alpine, NixOS, Mint), and extracts the kernel + initrd paths a bootloader needs to hand off via kexec_file_load(2).

Part of the aegis-boot rescue environment — a signed-chain UEFI Secure Boot stick that boots any ISO.

Design

• No unsafe. #![forbid(unsafe_code)] at the crate level. This crate parses untrusted ISO content; it has no business calling raw syscalls.
• Stateless. No global state, no filesystem mounts, no network. Caller supplies paths; parser returns structured data.
• No_std capable via the std feature flag (on by default).

Supported layouts

Distribution	Detection marker
Arch Linux	/arch/boot/x86_64/vmlinuz-linux
Debian / Ubuntu	/install/, /casper/, /.disk/, /pool/, or /dists/
Fedora	/images/pxeboot/
RHEL / Rocky / Alma	Same as Fedora; distinct lockdown policy recorded separately
Alpine	/boot/vmlinuz-lts + /boot/initramfs-lts
NixOS	/boot/bzImage
Linux Mint	Debian-family layout in /casper/

Usage

// Illustrative shape only. Caller supplies an `IsoEnvironment` —
// trait for mount/unmount + metadata. The production impl shells
// out to mount(8); tests use `MockIsoEnvironment` for per-test
// in-memory fixtures. See the in-repo integration tests
// (crates/iso-parser/src/lib.rs::tests) for concrete call sites.
use iso_parser::IsoParser;
use std::path::Path;

let env: MyIsoEnvironment = /* ... */;
let parser = IsoParser::new(env);
let entries = parser
    .scan_directory(Path::new("/mnt/iso"))
    .await?;
for entry in entries {
    println!("kernel: {}", entry.kernel.display());
    println!("initrd: {}", entry.initrd.display());
}

The text fence keeps this illustrative — the concrete types MyIsoEnvironment + the ?/await plumbing are consumer-specific.

See the API docs for the full surface.

Status

Pre-1.0. API is settling through real-hardware validation on the parent project’s test fleet (Framework / ThinkPad / Dell). Publishing to crates.io at 1.0. Until then, consume via the aegis-boot workspace.

License

Licensed under either of Apache-2.0 or MIT at your option.

---

Safety

forbid(unsafe_code) at the crate level — iso-parser ships to crates.io per #51 and a library that parses untrusted ISO content has no business calling raw syscalls. The kexec syscall lives in kexec-loader, the only crate in the workspace that’s exempt from this constraint.

Supported Distributions

• Arch Linux: /boot/ contains vmlinuz and initrd.img
• Debian/Ubuntu: /install/ or /casper/ contains vmlinuz and initrd.gz
• Fedora: /images/pxeboot/ contains vmlinuz and initrd.img

Usage

// Illustrative only — OsIsoEnvironment doesn't exist in this
// crate (real callers supply their own IsoEnvironment impl).
// `text` fence so this doesn't compile under `cargo test --
// --ignored` either.
use iso_parser::{IsoParser, OsIsoEnvironment};
use std::path::Path;

async fn example() {
    let parser = IsoParser::new(OsIsoEnvironment::new());
    let entries = parser.scan_directory(Path::new("/media/isos")).await?;
    for entry in entries {
        println!("Found: {} ({:?})", entry.label, entry.distribution);
    }
}

Structs

BootEntry

Represents a discovered boot entry from an ISO

IsoParser

ISO Parser - main entry point for boot discovery

OsIsoEnvironment

OS-specific implementation of IsoEnvironment

ScanFailure

A single ISO file that failed to yield boot entries during a directory scan.

ScanReport

Result of a directory scan — successful boot entries plus any per-file failures that the caller should surface to the user.

Enums

Distribution

Supported distribution families.

IsoError

Errors that can occur during ISO parsing

ScanFailureKind

Structured classification of why an ISO failed to yield boot entries. A 1-to-1 map from the per-file variants of IsoError.

Traits

IsoEnvironment

Environment abstraction for file system and OS operations

Functions

read_pretty_name

Best-effort “friendly” distro name for a mounted ISO.