1use std::collections::{HashMap, HashSet};
39use std::fs;
40use std::path::{Path, PathBuf};
41
42use anyhow::{Context, Result, anyhow, bail};
43use sha2::{Digest, Sha256};
44
45use crate::cache::{CacheArtifacts, CacheDir, KernelMetadata, KernelSource};
46use crate::distro::extract::{
47 ExtractedKernel, ensure_arch_matches_host, extract_kernel_packages, extract_vmlinux,
48 module_closure, package_arch,
49};
50use crate::distro::repo::{DistroKind, PackageRef, ResolvedDistroKernel, resolve_distro_kernel};
51
52const BOOT_CRITICAL: &[(&str, &str)] = &[
57 ("CONFIG_VIRTIO", "virtio"),
58 ("CONFIG_VIRTIO_MMIO", "virtio_mmio"),
59 ("CONFIG_VIRTIO_CONSOLE", "virtio_console"),
60];
61
62const FEATURE_MODULES: &[(&str, &str)] = &[
68 #[cfg(target_arch = "x86_64")]
69 ("CONFIG_VIRTIO_PCI", "virtio_pci"),
70 ("CONFIG_VIRTIO_BLK", "virtio_blk"),
71 ("CONFIG_VIRTIO_NET", "virtio_net"),
72 ("CONFIG_BTRFS_FS", "btrfs"),
73];
74
75const WARN_EXTRA: &[(&str, &str)] = &[
79 (
80 "CONFIG_KALLSYMS_ALL",
81 "monitor kallsyms symbol resolution will be less complete",
82 ),
83 (
84 "CONFIG_IKCONFIG_PROC",
85 "/proc/config.gz unavailable for in-guest config inspection",
86 ),
87 (
88 "CONFIG_IKHEADERS",
89 "/sys/kernel/kheaders.tar.xz absent — bpftrace/BCC in shell mode \
90 cannot fall back to in-kernel headers",
91 ),
92 (
93 "CONFIG_FTRACE_SYSCALLS",
94 "syscall tracepoints (tracepoint:syscalls:*) unavailable",
95 ),
96];
97
98#[derive(Clone, Copy, PartialEq, Eq, Debug)]
100enum OptState {
101 Builtin,
103 Module,
105 Off,
107}
108
109struct ConfigStates(HashMap<String, OptState>);
111
112impl ConfigStates {
113 fn parse(text: &str) -> Self {
114 let mut map = HashMap::new();
115 for line in text.lines() {
116 let line = line.trim();
117 if let Some(rest) = line.strip_prefix("# ")
118 && let Some(sym) = rest.strip_suffix(" is not set")
119 && sym.starts_with("CONFIG_")
120 {
121 map.insert(sym.to_string(), OptState::Off);
122 } else if line.starts_with("CONFIG_")
123 && let Some((sym, val)) = line.split_once('=')
124 {
125 let state = match val {
126 "m" => OptState::Module,
127 "n" => OptState::Off,
128 _ => OptState::Builtin,
129 };
130 map.insert(sym.to_string(), state);
131 }
132 }
133 ConfigStates(map)
134 }
135
136 fn state(&self, opt: &str) -> OptState {
137 self.0.get(opt).copied().unwrap_or(OptState::Off)
138 }
139
140 fn is_enabled(&self, opt: &str) -> bool {
141 matches!(self.state(opt), OptState::Builtin | OptState::Module)
142 }
143}
144
145#[derive(Debug)]
147struct GateResult {
148 critical: Vec<&'static str>,
151 feature: Vec<&'static str>,
155}
156
157fn gate_config(extracted: &ExtractedKernel) -> Result<GateResult> {
175 let kernel_label = &extracted.kernel_release;
176 let Some(config_path) = extracted.config.as_deref() else {
177 if extracted.modules_dir.is_some() {
178 tracing::warn!(
179 kernel = %kernel_label,
180 "prebuilt kernel shipped no .config — gating boot-critical \
181 virtio drivers on the module tree (modules.builtin + \
182 modules.dep) instead; config-derived feature warnings are \
183 unavailable for this kernel"
184 );
185 return Ok(GateResult {
186 critical: BOOT_CRITICAL.iter().map(|(_, m)| *m).collect(),
187 feature: FEATURE_MODULES.iter().map(|(_, m)| *m).collect(),
188 });
189 }
190 tracing::warn!(
191 kernel = %kernel_label,
192 "prebuilt kernel shipped no .config — skipping config gate. If the \
193 guest hangs at boot, the kernel likely lacks CONFIG_VIRTIO_MMIO / \
194 CONFIG_VIRTIO_CONSOLE (which ktstr needs for its console/control port)."
195 );
196 return Ok(GateResult {
197 critical: Vec::new(),
198 feature: Vec::new(),
199 });
200 };
201 let text = fs::read_to_string(config_path)
202 .with_context(|| format!("read extracted config {}", config_path.display()))?;
203 let states = ConfigStates::parse(&text);
204
205 let mut critical: Vec<&'static str> = Vec::new();
206 let mut missing_critical: Vec<&'static str> = Vec::new();
207 for (opt, module) in BOOT_CRITICAL {
208 match states.state(opt) {
209 OptState::Builtin => {}
210 OptState::Module => critical.push(module),
211 OptState::Off => missing_critical.push(opt),
212 }
213 }
214 if !missing_critical.is_empty() {
215 bail!(
216 "prebuilt kernel {kernel_label} cannot boot under ktstr: \
217 boot-critical option(s) {missing_critical:?} are neither =y nor =m. \
218 ktstr presents its console + host control port over the virtio-MMIO \
219 transport, so without these drivers the guest hangs before reaching \
220 userspace. This kernel is unsupported."
221 );
222 }
223
224 let mut feature: Vec<&'static str> = Vec::new();
225 for (opt, module) in FEATURE_MODULES {
226 match states.state(opt) {
227 OptState::Module => feature.push(module),
228 OptState::Builtin => {}
229 OptState::Off => tracing::warn!(
230 kernel = kernel_label,
231 option = opt,
232 "not enabled — the corresponding ktstr feature (disk / NIC / btrfs \
233 disk) will not work with this kernel; plain boots are unaffected"
234 ),
235 }
236 }
237
238 let handled: HashSet<&str> = BOOT_CRITICAL
243 .iter()
244 .chain(FEATURE_MODULES.iter())
245 .map(|(opt, _)| *opt)
246 .collect();
247 for (opt, hint) in crate::cli::critical_config_options() {
248 if handled.contains(opt) || states.is_enabled(opt) {
249 continue;
250 }
251 tracing::warn!(
252 kernel = kernel_label,
253 option = opt,
254 "not enabled in this prebuilt kernel — {hint}"
255 );
256 }
257 for (opt, effect) in WARN_EXTRA {
258 if !states.is_enabled(opt) {
259 tracing::warn!(
260 kernel = kernel_label,
261 option = opt,
262 "not enabled in this prebuilt kernel — {effect}"
263 );
264 }
265 }
266
267 Ok(GateResult { critical, feature })
268}
269
270fn select_boot_modules(extracted: &ExtractedKernel, gate: &GateResult) -> Result<Vec<PathBuf>> {
276 if gate.critical.is_empty() && gate.feature.is_empty() {
277 return Ok(Vec::new());
278 }
279 let modules_dir = extracted.modules_dir.as_ref().ok_or_else(|| {
280 anyhow!(
281 "kernel needs loadable modules but the package(s) carried no module \
282 tree — cannot assemble a bootable module set"
283 )
284 })?;
285 let release = &extracted.kernel_release;
286
287 let mut out: Vec<PathBuf> = Vec::new();
288 let mut seen: HashSet<PathBuf> = HashSet::new();
289
290 let crit = module_closure(modules_dir, release, &gate.critical).with_context(|| {
293 format!(
294 "prebuilt kernel {release} neither builds in nor ships a \
295 boot-critical virtio module among {:?} — ktstr cannot reach its \
296 console/host control port without it, so this kernel is unsupported \
297 (some distros split virtio-console into a subpackage the resolver \
298 must include)",
299 gate.critical
300 )
301 })?;
302 for p in crit {
303 if seen.insert(p.clone()) {
304 out.push(p);
305 }
306 }
307
308 for module in &gate.feature {
311 match module_closure(modules_dir, release, std::slice::from_ref(module)) {
312 Ok(mods) => {
313 for p in mods {
314 if seen.insert(p.clone()) {
315 out.push(p);
316 }
317 }
318 }
319 Err(e) => tracing::warn!(
320 module = module,
321 "declared =m but not shipped by this kernel ({e:#}); the \
322 corresponding disk/NIC/btrfs feature will not work"
323 ),
324 }
325 }
326
327 Ok(out)
328}
329
330pub(crate) fn install_extracted(
337 cache_key: &str,
338 extracted: &ExtractedKernel,
339 modules: &[PathBuf],
340 source: KernelSource,
341) -> Result<PathBuf> {
342 let (arch, image_name) = crate::fetch::arch_info();
343 let meta = KernelMetadata::new(source, arch, image_name, crate::test_support::now_iso8601())
344 .with_version(&extracted.kernel_release);
345
346 let mut artifacts = CacheArtifacts::new(&extracted.image).with_modules(modules);
347 if let Some(vmlinux) = extracted.vmlinux.as_deref() {
348 artifacts = artifacts.with_vmlinux(vmlinux);
349 }
350 if let Some(config) = extracted.config.as_deref() {
351 artifacts = artifacts.with_config(config);
352 }
353
354 let cache = CacheDir::new()?;
355 let entry = cache.store(cache_key, &artifacts, &meta).with_context(|| {
356 format!(
357 "install prebuilt kernel {} into cache",
358 extracted.kernel_release
359 )
360 })?;
361 Ok(entry.path)
362}
363
364pub(crate) fn scratch_dir() -> Result<tempfile::TempDir> {
370 let root = crate::cache::resolve_cache_root_with_suffix("kernels")?;
371 fs::create_dir_all(&root).with_context(|| format!("create cache root {}", root.display()))?;
372 tempfile::Builder::new()
373 .prefix(".acquire-")
374 .tempdir_in(&root)
375 .with_context(|| "create acquire scratch dir")
376}
377
378fn distro_cache_key(resolved: &ResolvedDistroKernel) -> Result<String> {
385 let primary = resolved
386 .packages
387 .first()
388 .ok_or_else(|| anyhow!("distro resolver returned no kernel packages"))?;
389 let sha12 = primary.sha256.get(..12).unwrap_or(&primary.sha256);
390 Ok(format!(
391 "distro-{}-{}-{}-pkg{}",
392 sanitize_key_part(&resolved.distro),
393 sanitize_key_part(&resolved.kernel_release),
394 resolved.arch,
395 sha12,
396 ))
397}
398
399fn local_cache_key(file_hashes: &[String], arch: &str) -> String {
403 let mut sorted: Vec<&str> = file_hashes.iter().map(String::as_str).collect();
404 sorted.sort_unstable();
405 let mut h = Sha256::new();
406 for fh in sorted {
407 h.update(fh.as_bytes());
408 }
409 let combined = hex::encode(h.finalize());
410 format!("pkg-{}-{arch}", &combined[..12])
411}
412
413fn sanitize_key_part(s: &str) -> String {
418 s.chars()
419 .map(|c| {
420 if c.is_ascii_alphanumeric() || matches!(c, '.' | '_' | '-') {
421 c
422 } else {
423 '_'
424 }
425 })
426 .collect()
427}
428
429fn sha256_file(path: &Path) -> Result<String> {
431 use std::io::Read;
432 let mut file = fs::File::open(path).with_context(|| format!("open {}", path.display()))?;
433 let mut hasher = Sha256::new();
434 let mut buf = [0u8; 65536];
435 loop {
436 let n = file
437 .read(&mut buf)
438 .with_context(|| format!("read {}", path.display()))?;
439 if n == 0 {
440 break;
441 }
442 hasher.update(&buf[..n]);
443 }
444 Ok(hex::encode(hasher.finalize()))
445}
446
447fn try_package_urls<T, F>(package: &PackageRef, attempt: F) -> Result<T>
455where
456 F: FnMut(&str) -> Result<T>,
457{
458 try_package_urls_with(package, crate::fetch::git_operation_interrupted, attempt)
459}
460
461fn try_package_urls_with<T, I, F>(
462 package: &PackageRef,
463 mut interrupted: I,
464 mut attempt: F,
465) -> Result<T>
466where
467 I: FnMut() -> bool,
468 F: FnMut(&str) -> Result<T>,
469{
470 let urls: Vec<&str> = std::iter::once(package.url.as_str())
471 .chain(package.alternate_urls.iter().map(String::as_str))
472 .collect();
473 let mut failures = Vec::with_capacity(urls.len());
474
475 for (index, url) in urls.iter().copied().enumerate() {
476 match attempt(url) {
477 Ok(value) => return Ok(value),
478 Err(error) if interrupted() => {
479 return Err(error).with_context(|| format!("download {} from {url}", package.name));
480 }
481 Err(error) => {
482 failures.push(format!("{url}: {error:#}"));
483 if index + 1 < urls.len() {
484 tracing::warn!(
485 package = %package.name,
486 failed_url = url,
487 next_url = urls[index + 1],
488 error = %format!("{error:#}"),
489 "official package origin failed; trying independent origin",
490 );
491 }
492 }
493 }
494 }
495
496 bail!(
497 "all official download origins failed for {}: {}",
498 package.name,
499 failures.join("; ")
500 )
501}
502
503pub fn acquire_distro_kernel(
520 kind: DistroKind,
521 release: Option<&str>,
522 cli_label: &str,
523 mp: Option<&crate::cli::FetchProgress>,
524) -> Result<PathBuf> {
525 if kind == DistroKind::Gke {
526 return crate::distro::gke::acquire_gke_kernel(release, cli_label, mp);
527 }
528 let resolved =
529 resolve_distro_kernel(kind, release).with_context(|| "resolve distro kernel metadata")?;
530 let cache_key = distro_cache_key(&resolved)?;
531
532 let cache = CacheDir::new()?;
533 if let Some(entry) = cache.lookup(&cache_key) {
534 tracing::info!(cache_key = %cache_key, "distro kernel cache hit");
535 return Ok(entry.path);
536 }
537
538 let msg = format!(
539 "{cli_label}: resolving {} kernel {} ({} package(s) + {} debuginfo)",
540 resolved.distro,
541 resolved.kernel_release,
542 resolved.packages.len(),
543 resolved.debuginfo.len(),
544 );
545 match mp {
546 Some(fp) => fp.println(&msg),
547 None => eprintln!("{msg}"),
548 }
549 if resolved.debuginfo.is_empty() {
550 let warn = format!(
556 "{cli_label}: {} publishes no kernel debuginfo — proceeding \
557 without vmlinux; monitor features that need it (symbolized \
558 stacks, probe file:line) will be unavailable for this kernel",
559 resolved.distro,
560 );
561 match mp {
562 Some(fp) => fp.println(&warn),
563 None => eprintln!("{warn}"),
564 }
565 tracing::warn!(distro = %resolved.distro, "no debuginfo published; caching kernel without vmlinux");
566 }
567
568 let scratch = scratch_dir()?;
569 let download_dir = scratch.path().join("pkgs");
570 fs::create_dir_all(&download_dir)?;
571
572 let download = |pkg: &PackageRef| -> Result<PathBuf> {
575 let file_name = pkg
576 .url
577 .rsplit('/')
578 .next()
579 .filter(|s| !s.is_empty())
580 .unwrap_or(&pkg.name);
581 let dest = download_dir.join(file_name);
582 try_package_urls(pkg, |url| {
583 crate::fetch::download_verified_file(url, &dest, &pkg.sha256, &pkg.name, cli_label, mp)
584 })
585 .with_context(|| format!("download {}", pkg.name))?;
586 if let Some(expected) = pkg.size {
587 let actual = fs::metadata(&dest)
588 .with_context(|| format!("stat downloaded package {}", dest.display()))?
589 .len();
590 if actual != expected {
591 bail!(
592 "downloaded package {} has size {actual}, expected {expected}",
593 pkg.name
594 );
595 }
596 }
597 ensure_arch_matches_host(&package_arch(&dest)?, &dest)?;
598 Ok(dest)
599 };
600
601 let extract_dir = scratch.path().join("tree");
607 let kernel_paths: Vec<PathBuf> = resolved
608 .packages
609 .iter()
610 .map(&download)
611 .collect::<Result<_>>()?;
612 let kernel_refs: Vec<&Path> = kernel_paths.iter().map(PathBuf::as_path).collect();
613 let mut extracted = extract_kernel_packages(&kernel_refs, &extract_dir)
614 .with_context(|| format!("extract {} packages", resolved.distro))?;
615
616 let gate = gate_config(&extracted)?;
617 let modules = select_boot_modules(&extracted, &gate)?;
618
619 if !resolved.debuginfo.is_empty() {
623 let debug_paths: Vec<PathBuf> = resolved
624 .debuginfo
625 .iter()
626 .map(&download)
627 .collect::<Result<_>>()?;
628 let debug_refs: Vec<&Path> = debug_paths.iter().map(PathBuf::as_path).collect();
629 extracted.vmlinux = extract_vmlinux(&debug_refs, &extract_dir, &extracted.kernel_release)
630 .with_context(|| format!("extract {} debuginfo", resolved.distro))?;
631 }
632
633 let packages_meta: Vec<String> = resolved
634 .packages
635 .iter()
636 .chain(resolved.debuginfo.iter())
637 .map(|p| format!("{}-{}", p.name, p.version))
638 .collect();
639 let source = KernelSource::DistroPackage {
640 distro: resolved.distro.clone(),
641 packages: packages_meta,
642 };
643 install_extracted(&cache_key, &extracted, &modules, source)
644}
645
646pub fn acquire_package_kernel(paths: &[PathBuf]) -> Result<PathBuf> {
653 if paths.is_empty() {
654 bail!("acquire_package_kernel: no package files supplied");
655 }
656 for p in paths {
657 if !p.is_file() {
658 bail!("kernel package not found: {}", p.display());
659 }
660 }
661
662 let (arch, _) = crate::fetch::arch_info();
663 let hashes: Vec<String> = paths
664 .iter()
665 .map(|p| sha256_file(p))
666 .collect::<Result<_>>()?;
667 let cache_key = local_cache_key(&hashes, arch);
668
669 let cache = CacheDir::new()?;
670 if let Some(entry) = cache.lookup(&cache_key) {
671 tracing::info!(cache_key = %cache_key, "local package kernel cache hit");
672 return Ok(entry.path);
673 }
674
675 for p in paths {
677 ensure_arch_matches_host(&package_arch(p)?, p)?;
678 }
679
680 let scratch = scratch_dir()?;
681 let extract_dir = scratch.path().join("tree");
682 let refs: Vec<&Path> = paths.iter().map(PathBuf::as_path).collect();
683 let extracted = extract_kernel_packages(&refs, &extract_dir)
684 .with_context(|| "extract local kernel packages")?;
685 let gate = gate_config(&extracted)?;
686 let modules = select_boot_modules(&extracted, &gate)?;
687
688 let packages_meta: Vec<String> = paths
689 .iter()
690 .filter_map(|p| p.file_name().map(|n| n.to_string_lossy().into_owned()))
691 .collect();
692 let source = KernelSource::LocalPackage {
693 packages: packages_meta,
694 };
695 install_extracted(&cache_key, &extracted, &modules, source)
696}
697
698#[cfg(test)]
699#[path = "acquire_tests.rs"]
700mod tests;