bootc_lib/
ukify.rs

1//! Build Unified Kernel Images (UKI) using ukify.
2//!
3//! This module provides functionality to build UKIs by computing the necessary
4//! arguments from a container image and invoking the ukify tool.
5
6use std::ffi::OsString;
7use std::process::Command;
8
9use anyhow::{Context, Result};
10use bootc_kernel_cmdline::utf8::Cmdline;
11use bootc_utils::CommandRunExt;
12use camino::Utf8Path;
13use cap_std_ext::cap_std::fs::Dir;
14use fn_error_context::context;
15
16use crate::bootc_composefs::digest::compute_composefs_digest;
17use crate::bootc_composefs::status::ComposefsCmdline;
18
19/// Build a UKI from the given rootfs.
20///
21/// This function:
22/// 1. Verifies that ukify is available
23/// 2. Finds the kernel in the rootfs
24/// 3. Computes the composefs digest
25/// 4. Reads kernel arguments from kargs.d
26/// 5. Appends any additional kargs provided via --karg
27/// 6. Invokes ukify with computed arguments plus any pass-through args
28#[context("Building UKI")]
29pub(crate) fn build_ukify(
30    rootfs: &Utf8Path,
31    extra_kargs: &[String],
32    args: &[OsString],
33    allow_missing_fsverity: bool,
34) -> Result<()> {
35    // Warn if --karg is used (temporary workaround)
36    if !extra_kargs.is_empty() {
37        tracing::warn!(
38            "The --karg flag is temporary and will be removed as soon as possible \
39            (https://github.com/bootc-dev/bootc/issues/1826)"
40        );
41    }
42
43    // Verify ukify is available
44    if !crate::utils::have_executable("ukify")? {
45        anyhow::bail!(
46            "ukify executable not found in PATH. Please install systemd-ukify or equivalent."
47        );
48    }
49
50    // Open the rootfs directory
51    let root = Dir::open_ambient_dir(rootfs, cap_std_ext::cap_std::ambient_authority())
52        .with_context(|| format!("Opening rootfs {rootfs}"))?;
53
54    // Find the kernel
55    let kernel = crate::kernel::find_kernel(&root)?
56        .ok_or_else(|| anyhow::anyhow!("No kernel found in {rootfs}"))?;
57
58    // Extract vmlinuz and initramfs paths, or bail if this is already a UKI
59    let (vmlinuz_path, initramfs_path) = match kernel.k_type {
60        crate::kernel::KernelType::Vmlinuz { path, initramfs } => (path, initramfs),
61        crate::kernel::KernelType::Uki { path, .. } => {
62            anyhow::bail!("Cannot build UKI: rootfs already contains a UKI at {path}");
63        }
64    };
65
66    // Verify kernel and initramfs exist
67    if !root
68        .try_exists(&vmlinuz_path)
69        .context("Checking for vmlinuz")?
70    {
71        anyhow::bail!("Kernel not found at {vmlinuz_path}");
72    }
73    if !root
74        .try_exists(&initramfs_path)
75        .context("Checking for initramfs")?
76    {
77        anyhow::bail!("Initramfs not found at {initramfs_path}");
78    }
79
80    // Compute the composefs digest
81    let composefs_digest = compute_composefs_digest(rootfs, None)?;
82
83    // Get kernel arguments from kargs.d
84    let mut cmdline = crate::bootc_kargs::get_kargs_in_root(&root, std::env::consts::ARCH)?;
85
86    // Add the composefs digest
87    cmdline.extend(&Cmdline::from(
88        ComposefsCmdline::build(&composefs_digest, allow_missing_fsverity).to_string(),
89    ));
90
91    // Add any extra kargs provided via --karg
92    for karg in extra_kargs {
93        cmdline.extend(&Cmdline::from(karg));
94    }
95
96    let cmdline_str = cmdline.to_string();
97
98    // Build the ukify command with cwd set to rootfs so paths can be relative
99    let mut cmd = Command::new("ukify");
100    cmd.current_dir(rootfs);
101    cmd.arg("build")
102        .arg("--linux")
103        .arg(&vmlinuz_path)
104        .arg("--initrd")
105        .arg(&initramfs_path)
106        .arg("--uname")
107        .arg(&kernel.kernel.version)
108        .arg("--cmdline")
109        .arg(&cmdline_str)
110        .arg("--os-release")
111        .arg("@usr/lib/os-release");
112
113    // Add pass-through arguments
114    cmd.args(args);
115
116    tracing::debug!("Executing ukify: {:?}", cmd);
117
118    // Run ukify
119    cmd.run_inherited().context("Running ukify")?;
120
121    Ok(())
122}
123
124#[cfg(test)]
125mod tests {
126    use super::*;
127    use std::fs;
128
129    #[test]
130    fn test_build_ukify_no_kernel() {
131        let tempdir = tempfile::tempdir().unwrap();
132        let path = Utf8Path::from_path(tempdir.path()).unwrap();
133
134        let result = build_ukify(path, &[], &[], false);
135        assert!(result.is_err());
136        let err = format!("{:#}", result.unwrap_err());
137        assert!(
138            err.contains("No kernel found") || err.contains("ukify executable not found"),
139            "Unexpected error message: {err}"
140        );
141    }
142
143    #[test]
144    fn test_build_ukify_already_uki() {
145        let tempdir = tempfile::tempdir().unwrap();
146        let path = Utf8Path::from_path(tempdir.path()).unwrap();
147
148        // Create a UKI structure
149        fs::create_dir_all(tempdir.path().join("boot/EFI/Linux")).unwrap();
150        fs::write(tempdir.path().join("boot/EFI/Linux/test.efi"), b"fake uki").unwrap();
151
152        let result = build_ukify(path, &[], &[], false);
153        assert!(result.is_err());
154        let err = format!("{:#}", result.unwrap_err());
155        assert!(
156            err.contains("already contains a UKI") || err.contains("ukify executable not found"),
157            "Unexpected error message: {err}"
158        );
159    }
160}
bootc_lib/ukify.rs

bootc_lib/
ukify.rs
