diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1dd2725c17..05f8884cc9 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -553,7 +553,9 @@ jobs: # `is_wsl_host`, `/run/.containerenv` and `/proc/1/cgroup` via # `probe_container`, and both `/etc/os-release` reads (the distro # fields and the distro name, in - # `os_release_reads_follow_the_simulated_host_root`). The other routed + # `os_release_reads_follow_the_simulated_host_root` and, for the + # `/usr/lib/os-release` fallback, in + # `os_release_reads_fall_back_to_usr_lib_when_etc_is_absent`). The other routed # reads (`/dev/dri`, `/sys/class/drm`, `/sys/module/amdgpu`, the other # `/proc` files, the modprobe directories, the `/usr/lib/wsl/lib` and # ROCDXG checks) have no planted-root unit assertion; they are covered diff --git a/apps/rocm/src/driver_install.rs b/apps/rocm/src/driver_install.rs index 7c7c1bb812..b5c5136160 100644 --- a/apps/rocm/src/driver_install.rs +++ b/apps/rocm/src/driver_install.rs @@ -25,7 +25,7 @@ use rocm_core::{AppPaths, ExamineSummary, shell_command_for_host}; use serde::{Deserialize, Serialize}; use crate::cli_report; -use crate::runtime_install_finalize::{empty_as_unknown, read_os_release}; +use crate::runtime_install_finalize::{empty_as_unknown, real_os_release}; pub(crate) fn install_driver( paths: &AppPaths, @@ -35,11 +35,11 @@ pub(crate) fn install_driver( ) -> std::result::Result { let examine = ExamineSummary::gather().map_err(|source| DriverInstallError::new(source, false))?; - let os_release = read_os_release().unwrap_or_default(); + let os_release = real_os_release(); // The only place the real privilege level is read; every builder below takes // it as a parameter so both branches stay testable on any host. let plan = - build_driver_install_plan(&examine, &os_release, dkms, PrivilegeEscalation::detect()); + build_driver_install_plan_read(&examine, &os_release, dkms, PrivilegeEscalation::detect()); let mut output = render_driver_install_plan(&plan, yes, dry_run); if !yes || dry_run || !plan.supported || !plan.mutating { return Ok(DriverInstallResult { @@ -798,11 +798,59 @@ fn wsl_rocdxg_driver_plan(escalation: PrivilegeEscalation) -> DriverInstallPlan } } +/// [`build_driver_install_plan_at`], naming `/etc/os-release` in any +/// unreadable-line message. Only the unit tests fixturing bare +/// `os_release_text` (never the real host) use this one; the real call site +/// in [`install_driver`] knows the path it actually read and calls +/// [`build_driver_install_plan_read`] directly. +#[cfg(test)] fn build_driver_install_plan( examine: &ExamineSummary, os_release_text: &str, dkms: bool, escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + build_driver_install_plan_at( + examine, + "/etc/os-release", + os_release_text, + dkms, + escalation, + ) +} + +/// The plan for a release file that cannot be read as a distro at all — a +/// malformed line ([`build_driver_install_plan_at`]'s own early return) or a +/// file that exists but could not be read +/// ([`build_driver_install_plan_read`]'s `Unreadable` branch). Both name +/// `reason`, never a distro, and differ only in it: shared here, including +/// `repo_version`'s own resolution, so a new early branch — or a bumped +/// default — added to one is not silently absent from the other. +fn unreadable_os_release_plan(reason: String) -> DriverInstallPlan { + DriverInstallPlan { + supported: false, + mutating: false, + policy: "unreadable_os_release".to_owned(), + os_id: String::new(), + version_id: String::new(), + codename: String::new(), + repo_version: resolve_shell_default_template("${ROCM_CLI_AMDGPU_VERSION:-7.2.4}"), + reason, + preflight_checks: Vec::new(), + commands: Vec::new(), + checks: vec!["rocm examine".to_owned()], + reboot_required: false, + } +} + +/// [`build_driver_install_plan`], naming `os_release_path` instead of always +/// `/etc/os-release` in an unreadable-line message. +fn build_driver_install_plan_at( + examine: &ExamineSummary, + os_release_path: &str, + os_release_text: &str, + dkms: bool, + escalation: PrivilegeEscalation, ) -> DriverInstallPlan { // Resolve the AMD graphics version and amdgpu-install package release once, // here at plan-build time, so the concrete values are baked into both the @@ -841,24 +889,11 @@ fn build_driver_install_plan( let os_release = match rocm_core::os_release::parse(os_release_text) { Ok(fields) => fields, Err(unreadable) => { - return DriverInstallPlan { - supported: false, - mutating: false, - policy: "unreadable_os_release".to_owned(), - os_id: String::new(), - version_id: String::new(), - codename: String::new(), - repo_version, - reason: format!( - "/etc/os-release {unreadable}; no driver commands were planned \ - because the distro cannot be read. To fix it, {}.", - unreadable.fix() - ), - preflight_checks: Vec::new(), - commands: Vec::new(), - checks: vec!["rocm examine".to_owned()], - reboot_required: false, - }; + return unreadable_os_release_plan(format!( + "{os_release_path} {unreadable}; no driver commands were planned \ + because the distro cannot be read. To fix it, {}.", + unreadable.fix() + )); } }; let field = |key: &str| os_release.get(key).cloned(); @@ -971,6 +1006,36 @@ fn build_driver_install_plan( } } +/// [`build_driver_install_plan_at`] for `read`, naming the file actually read +/// in an unreadable-line message, and reporting a file that exists but could +/// not be read as itself rather than as an unknown distribution. +/// +/// Without the latter, a host whose `/etc/os-release` is merely unreadable +/// (permission denied, a directory in its place) would plan nothing and say +/// "no commands were guessed for this distro" — the same message an actually +/// unsupported distribution gets — sending the user looking for a support +/// gap instead of a filesystem problem. The Windows and WSL branches never +/// reach the os-release parse at all, so they are unaffected either way and +/// are left to the normal call below. +fn build_driver_install_plan_read( + examine: &ExamineSummary, + read: &rocm_core::hardware_root::OsRelease, + dkms: bool, + escalation: PrivilegeEscalation, +) -> DriverInstallPlan { + let reaches_os_release_parse = + examine.os != "windows" && !examine.wsl.as_ref().is_some_and(|wsl| wsl.is_wsl); + if reaches_os_release_parse + && let rocm_core::hardware_root::OsRelease::Unreadable { path, error } = read + { + return unreadable_os_release_plan(format!( + "{}; no driver commands were planned because the distro cannot be read.", + rocm_core::hardware_root::unreadable_prefix(path, error) + )); + } + build_driver_install_plan_at(examine, read.path(), read.text(), dkms, escalation) +} + /// Select a driver install plan for a distro whose `/etc/os-release` `ID` is not /// an AMD-documented distro, by falling back to its `ID_LIKE` base family. /// @@ -1875,6 +1940,161 @@ mod tests { ); } + /// `build_driver_install_plan_read` is the one seam `install_driver` hands + /// its `real_os_release()` result to. Both are now one-line delegations + /// to `hardware_root::read_os_release`, so reverting either back to a raw + /// `/etc/os-release` read is a type error here, not a silent regression. + /// This still pins the behaviour at the seam itself: an `OsRelease` that + /// says the fallback path was read plans exactly what a primary-path read + /// with the same content would. + #[test] + fn a_fallback_read_plans_exactly_like_a_primary_read() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let examine = test_examine("linux", false); + let fallback = rocm_core::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n".to_owned(), + }; + let primary = rocm_core::hardware_root::OsRelease::Found { + path: "/etc/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\n".to_owned(), + }; + + let from_fallback = + build_driver_install_plan_read(&examine, &fallback, true, PrivilegeEscalation::Sudo); + let from_primary = + build_driver_install_plan_read(&examine, &primary, true, PrivilegeEscalation::Sudo); + assert_eq!(from_fallback.os_id, "ubuntu"); + assert_eq!( + ( + from_fallback.os_id.clone(), + from_fallback.version_id.clone(), + from_fallback.codename.clone(), + from_fallback.reason.clone(), + from_fallback.execution_commands(), + ), + ( + from_primary.os_id.clone(), + from_primary.version_id.clone(), + from_primary.codename.clone(), + from_primary.reason.clone(), + from_primary.execution_commands(), + ), + ); + } + + /// A file that exists but could not be read plans nothing and names + /// itself, distinctly from both an unreadable *line* (which still comes + /// from a file that was read, see + /// [`an_unreadable_os_release_names_its_line_and_plans_nothing`]) and from + /// an unsupported distribution — which would send the user looking for a + /// support gap instead of a filesystem problem. + #[test] + fn an_unreadable_file_plans_nothing_and_names_itself() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!(plan.policy, "unreadable_os_release"); + assert!(!plan.supported); + assert!(plan.commands.is_empty(), "{:?}", plan.commands); + assert_eq!( + plan.reason, + "/usr/lib/os-release could not be read: denied; no driver commands were planned \ + because the distro cannot be read." + ); + } + + /// The same malformed line as + /// [`an_unreadable_os_release_names_its_line_and_plans_nothing`], but read + /// through the fallback path: the reason must name `/usr/lib/os-release`, + /// not `/etc/os-release`. That test only exercises the bare, + /// hardcoded-`/etc` `build_driver_install_plan`, so a regression that + /// hardcoded the path back into `build_driver_install_plan_read` would + /// still pass it. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let read = rocm_core::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nVERSION_CODENAME=noble\nunset ID\n".to_owned(), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!( + plan.reason, + "/usr/lib/os-release line 4 is not a plain assignment: \"unset ID\"; no driver \ + commands were planned because the distro cannot be read. To fix it, remove \ + that line or rewrite it as NAME=value." + ); + assert!(!plan.supported); + assert!(plan.commands.is_empty(), "{:?}", plan.commands); + assert_eq!(plan.policy, "unreadable_os_release"); + } + + /// On WSL, `build_driver_install_plan_read`'s `Unreadable` branch must + /// not fire at all: WSL has its own guest-side os-release probe (see + /// `examine.rs`'s `WSL_REMOTE_PROBE`), so the local Rust-side read this + /// function receives is never authoritative for a WSL host, and the plan + /// must stay the ordinary `wsl_rocdxg` one — not `unreadable_os_release` — + /// regardless of what it says. Without the `reaches_os_release_parse` + /// guard this would plan nothing on a WSL host whose local read happens + /// to come back `Unreadable`, even though the guest-side probe may read + /// the distro just fine. + #[test] + fn a_wsl_host_ignores_an_unreadable_local_os_release_read() { + let _env = scoped_rocdxg_env(); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("linux", true), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!(plan.policy, "wsl_rocdxg"); + assert!(plan.supported); + assert!(plan.mutating); + } + + /// The Windows half of the same `reaches_os_release_parse` guard: a + /// native Windows host's driver install is `windows_validate_only` + /// regardless of what the local read says, since the Linux driver + /// install this plan guards is never attempted there. Without this half + /// of the guard, a Windows host whose `real_os_release()` happens to come + /// back `Unreadable` would wrongly take the Linux-only + /// `unreadable_os_release` policy instead. + #[test] + fn a_windows_host_ignores_an_unreadable_local_os_release_read() { + let _env = ScopedTestEnv::with_amd_overrides_cleared(); + let read = rocm_core::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let plan = build_driver_install_plan_read( + &test_examine("windows", false), + &read, + true, + PrivilegeEscalation::Sudo, + ); + assert_eq!(plan.policy, "windows_validate_only"); + assert!(!plan.supported); + assert!(!plan.mutating); + } + /// With a duplicated key, the plan is built from the last assignment — the /// one a shell keeps, and the one `rocm examine` reports, since both read /// through `rocm_core::os_release`. diff --git a/apps/rocm/src/runtime_install_finalize.rs b/apps/rocm/src/runtime_install_finalize.rs index 23de4e8357..e1a4f2dba9 100644 --- a/apps/rocm/src/runtime_install_finalize.rs +++ b/apps/rocm/src/runtime_install_finalize.rs @@ -14,7 +14,6 @@ //! and read from `engines_cmd.rs`. use std::fmt::Write as _; -use std::fs; use std::path::{Path, PathBuf}; use std::process::{Command as ProcessCommand, Stdio}; @@ -149,15 +148,17 @@ pub(crate) const fn empty_as_unknown(value: &str) -> &str { if value.is_empty() { "" } else { value } } -/// The real host's `/etc/os-release`. +/// The real host's `/etc/os-release`, falling back to `/usr/lib/os-release` +/// when the former is absent (per `os-release(5)`). /// /// Deliberately not routed through `rocm_core::host_path`: every caller builds /// a package-manager plan (`apt`, `dnf`, `amdgpu-install`) that then runs /// against the real machine, so a simulated host root must not choose its /// distro. The descriptive distro name `examine` reports comes from -/// `rocm_core::detect_distro_name`, which does follow a simulated root. -pub(crate) fn read_os_release() -> Result { - fs::read_to_string("/etc/os-release").context("failed to read /etc/os-release") +/// `ExamineSummary::gather`'s `distro` field, which does follow a simulated +/// root. +pub(crate) fn real_os_release() -> rocm_core::hardware_root::OsRelease { + rocm_core::hardware_root::read_os_release(rocm_core::hardware_root::identity_path_for_str) } /// Run a command given as an argv vector directly, without going through a shell. @@ -202,8 +203,8 @@ pub(crate) fn ensure_openmpi_for_vllm(approved: bool) -> Result<()> { return Ok(()); } - let plan = rocm_core::openmpi::plan_for_os_release( - &read_os_release().unwrap_or_default(), + let plan = rocm_core::openmpi::plan_for_os_release_read( + &real_os_release(), rocm_core::openmpi::build_openmpi_install_plan, ); @@ -377,10 +378,7 @@ fn ensure_torch_runtime_dep(approved: bool, dep: &TorchRuntimeDep) { return; } - let plan = rocm_core::openmpi::plan_for_os_release( - &read_os_release().unwrap_or_default(), - dep.build_plan, - ); + let plan = rocm_core::openmpi::plan_for_os_release_read(&real_os_release(), dep.build_plan); println!("{} setup", dep.name); println!(" reason: {}", dep.reason); @@ -1970,6 +1968,8 @@ pub(crate) fn finalize_successful_sdk_install( #[cfg(test)] pub(crate) mod tests { + use std::fs; + use super::*; use crate::test_support::write_test_pip_runtime; use crate::tests::{ @@ -2082,13 +2082,25 @@ pub(crate) mod tests { assert_eq!(preferred_engine_for_sdk_family("gfx120X-all"), None); } + /// The real candidate path/text `real_os_release_ignores_a_simulated_host_root` + /// expects, read independently rather than by calling + /// `hardware_root::read_os_release` a second time. `Absent` and + /// `Unreadable` are not interchangeable: a non-`NotFound` error must + /// always report `Unreadable`, never silently fall through to `Absent`. + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + enum ExpectedOsRelease { + Found(&'static str, String), + Absent, + Unreadable(&'static str), + } + /// The package-manager plans run against the real machine, so a simulated /// host root must not change the distro they are built for: under a root - /// whose `/etc/os-release` names a different distro, `read_os_release` + /// whose `/etc/os-release` names a different distro, `real_os_release` /// still returns the real file. #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] #[test] - fn read_os_release_ignores_a_simulated_host_root() { + fn real_os_release_ignores_a_simulated_host_root() { let root = std::env::temp_dir().join(format!( "rocm-os-release-host-root-{}-{}", std::process::id(), @@ -2109,18 +2121,52 @@ pub(crate) mod tests { rocm_core::hardware_root::TEST_HOST_ROOT_ENV, &root.to_string_lossy(), ); - read_os_release().unwrap_or_default() + real_os_release() }; fs::remove_dir_all(&root).ok(); assert!( - !read.contains("planted-distro"), - "read the simulated root's os-release: {read:?}" - ); - assert_eq!( - read, - fs::read_to_string("/etc/os-release").unwrap_or_default() - ); + !read.text().contains("planted-distro"), + "read the simulated root's os-release: {:?}", + read.text() + ); + // Independent of `hardware_root::read_os_release`: rather than call + // the exact same helper with the same identity resolver `real_os_release` + // wraps one line away (which would pass even if its `.context(...)` + // call or resolver closure broke), read both candidate paths directly + // and apply the same existence-only fallback rule inline. This mirrors + // which variant is correct for each case, rather than accepting + // `Absent` or `Unreadable` interchangeably — see `ExpectedOsRelease`'s + // own doc comment for why that distinction matters. + let expected = match fs::read_to_string("/etc/os-release") { + Ok(text) => ExpectedOsRelease::Found("/etc/os-release", text), + Err(e) if e.kind() == std::io::ErrorKind::NotFound => { + match fs::read_to_string("/usr/lib/os-release") { + Ok(text) => ExpectedOsRelease::Found("/usr/lib/os-release", text), + Err(e2) if e2.kind() == std::io::ErrorKind::NotFound => { + ExpectedOsRelease::Absent + } + Err(_) => ExpectedOsRelease::Unreadable("/usr/lib/os-release"), + } + } + Err(_) => ExpectedOsRelease::Unreadable("/etc/os-release"), + }; + match expected { + ExpectedOsRelease::Found(path, text) => { + assert_eq!((read.path(), read.text()), (path, text.as_str())); + } + ExpectedOsRelease::Absent => assert!( + matches!(&read, rocm_core::hardware_root::OsRelease::Absent), + "expected Absent, got {read:?}" + ), + ExpectedOsRelease::Unreadable(path) => assert!( + matches!( + &read, + rocm_core::hardware_root::OsRelease::Unreadable { path: p, .. } if *p == path + ), + "expected Unreadable at {path}, got {read:?}" + ), + } } // The install report is only as honest as the reconciliation that reaches diff --git a/crates/rocm-core/src/diagnose.rs b/crates/rocm-core/src/diagnose.rs index 20306fdfd2..0dd22925d8 100644 --- a/crates/rocm-core/src/diagnose.rs +++ b/crates/rocm-core/src/diagnose.rs @@ -2421,7 +2421,8 @@ fn check_wsl_5_distro_too_old(e: &Examination, _symptom: &str) -> Diagnosis { "# wsl --install -d Ubuntu-24.04".to_owned(), ], fix_id: "fix-wsl-5-distro-too-old".to_owned(), - verify: "grep VERSION_ID /etc/os-release".to_owned(), + verify: "f=/etc/os-release; [ -e \"$f\" ] || f=/usr/lib/os-release; grep VERSION_ID \"$f\" 2>/dev/null | head -1" + .to_owned(), notes: vec![ "This is a hard floor, not a recommendation: Ubuntu 22.04 ships glibc 2.35, below the glibc 2.38 / GLIBCXX_3.4.32 that every published Lemonade embeddable is linked against, so the engine cannot start there at all.".to_owned(), ], diff --git a/crates/rocm-core/src/examine.rs b/crates/rocm-core/src/examine.rs index 27d7908feb..a29cfc68fe 100644 --- a/crates/rocm-core/src/examine.rs +++ b/crates/rocm-core/src/examine.rs @@ -736,7 +736,10 @@ fn probe_os(e: &mut Examination) { e.os_family = "linux".to_owned(); e.kernel_release = run("uname", &["-r"], SHORT).1.trim().to_owned(); e.kernel_cmdline = read_host_text("/proc/cmdline").trim().to_owned(); - record_distro(e, &read_host_text("/etc/os-release")); + record_distro( + e, + &crate::hardware_root::read_os_release(crate::hardware_root::host_path_for_str), + ); if let Some(param) = parse_iommu_param(&e.kernel_cmdline) { e.iommu_kernel_param = param; } @@ -751,21 +754,31 @@ fn probe_os(e: &mut Examination) { } } -/// Fill the distro fields from os-release `text`, through the same parser the -/// driver plan uses, so the two report the same distro. +/// Fill the distro fields from `read`, through the same parser the driver +/// plan uses, so the two report the same distro. /// -/// An unreadable file leaves both fields empty and says why in -/// `probe_failures`, naming the line — an empty distro with no explanation -/// would read as "nothing to report" rather than "something to fix". A missing -/// file reads as empty text, which is not a failure. -fn record_distro(e: &mut Examination, text: &str) { - match crate::os_release::parse(text) { +/// An unreadable line leaves both fields empty and says why in +/// `probe_failures`, naming the file actually read and the line — an empty +/// distro with no explanation would read as "nothing to report" rather than +/// "something to fix". A missing file reads as empty text, which is not a +/// failure; a file that exists but could not be read is, and is reported as +/// itself rather than as an unreadable line it never reached. +fn record_distro(e: &mut Examination, read: &crate::hardware_root::OsRelease) { + if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { + e.probe_failures.push(format!( + "{}; the distro is not reported.", + crate::hardware_root::unreadable_prefix(path, error) + )); + return; + } + match crate::os_release::parse(read.text()) { Ok(mut fields) => { e.distro_id = fields.remove("ID").unwrap_or_default(); e.distro_version = fields.remove("VERSION_ID").unwrap_or_default(); } Err(unreadable) => e.probe_failures.push(format!( - "/etc/os-release {unreadable}; the distro is not reported." + "{} {unreadable}; the distro is not reported.", + read.path() )), } } @@ -827,6 +840,12 @@ fn host_driver_fields(probe: crate::WslHostDriverProbe) -> (bool, Option /// /// `librocdxg` is globbed across `/opt/rocm*` for the same reason the in-guest /// probe resolves it across installs: a versioned root must not read as missing. +/// +/// The distro's `id`/`version` fields fall back from `/etc/os-release` to +/// `/usr/lib/os-release` per `os-release(5)`, matching every other reader in +/// this crate — this is the one that runs inside the distro over `wsl.exe` +/// rather than through [`crate::host_path`], so it needs its own copy of the +/// fallback rather than sharing `hardware_root::read_os_release`. const WSL_REMOTE_PROBE: &str = r#" echo "kernel=$(uname -r 2>/dev/null)" if [ -e /dev/dxg ]; then echo dxg=1; else echo dxg=0; fi @@ -848,11 +867,28 @@ if command -v rocminfo >/dev/null 2>&1; then else echo rocminfo=0 fi -. /etc/os-release 2>/dev/null +try_os_release() { + if [ -e "$1" ]; then . "$1" 2>/dev/null + elif [ -e "$2" ]; then . "$2" 2>/dev/null + fi +} +try_os_release /etc/os-release /usr/lib/os-release echo "id=${ID}" echo "version=${VERSION_ID}" "#; +/// The `try_os_release` shell function embedded in [`WSL_REMOTE_PROBE`]: sources +/// `$1`, falling back to `$2` per `os-release(5)` when `$1` does not exist — an +/// existence check (`[ -e ... ]`), not a readability one, so a permission-denied +/// primary is not silently replaced by a possibly stale fallback. +/// +/// Duplicated as its own constant, with the paths left as parameters, so the +/// test below can run this exact function body against temp-directory paths +/// instead of the real `/etc`; [`try_os_release_fn_is_embedded_in_the_wsl_remote_probe`] +/// guards against the two drifting apart. +#[cfg(test)] +const TRY_OS_RELEASE_FN: &str = "try_os_release() {\n if [ -e \"$1\" ]; then . \"$1\" 2>/dev/null\n elif [ -e \"$2\" ]; then . \"$2\" 2>/dev/null\n fi\n}"; + /// Parse `wsl.exe -l -q` into distribution names. /// /// `-q` prints one bare name per line, so the whole line is the name. It is NOT @@ -3152,7 +3188,9 @@ mod tests { let mut e = linux_host_with_a_gpu(); record_distro( &mut e, - "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\n", + &crate::hardware_root::OsRelease::found( + "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\n", + ), ); assert_eq!( e.probe_failures, @@ -3166,7 +3204,10 @@ mod tests { assert_eq!(e.compute_status(), "degraded"); let mut e = linux_host_with_a_gpu(); - record_distro(&mut e, "ID='ubuntu'\nVERSION_ID='24.04' # LTS\n"); + record_distro( + &mut e, + &crate::hardware_root::OsRelease::found("ID='ubuntu'\nVERSION_ID='24.04' # LTS\n"), + ); assert!(e.probe_failures.is_empty(), "{:?}", e.probe_failures); assert_eq!( (e.distro_id.as_str(), e.distro_version.as_str()), @@ -3176,10 +3217,64 @@ mod tests { // No file at all is not a failure: there is nothing to fix. let mut e = Examination::default(); - record_distro(&mut e, ""); + record_distro(&mut e, &crate::hardware_root::OsRelease::Absent); assert!(e.probe_failures.is_empty(), "{:?}", e.probe_failures); } + /// A file that exists but could not be read is reported as itself — not + /// folded into an empty, unreported distro the way `Absent` is, and not + /// pointing at the wrong candidate when the fallback was the one that + /// failed. + #[test] + fn an_unreadable_file_names_itself_instead_of_a_distro() { + let mut e = linux_host_with_a_gpu(); + record_distro( + &mut e, + &crate::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }, + ); + assert_eq!( + e.probe_failures, + vec![ + "/usr/lib/os-release could not be read: denied; the distro is not reported." + .to_owned() + ] + ); + assert_eq!((e.distro_id.as_str(), e.distro_version.as_str()), ("", "")); + assert_eq!(e.compute_status(), "degraded"); + } + + /// The same malformed line as + /// [`an_unreadable_os_release_names_its_line_instead_of_a_distro`], but + /// read through the fallback path: `probe_failures` must name + /// `/usr/lib/os-release`, not `/etc/os-release`. That test only exercises + /// [`crate::hardware_root::OsRelease::found`], which hardcodes + /// `/etc/os-release`, so a regression that hardcoded the path back into + /// `record_distro`'s message would still pass it. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path_in_probe_failures() { + let mut e = linux_host_with_a_gpu(); + record_distro( + &mut e, + &crate::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\n".to_owned(), + }, + ); + assert_eq!( + e.probe_failures, + vec![ + "/usr/lib/os-release line 3 is not a plain assignment: \"export ID=debian\"; \ + the distro is not reported." + .to_owned() + ] + ); + assert_eq!((e.distro_id.as_str(), e.distro_version.as_str()), ("", "")); + assert_eq!(e.compute_status(), "degraded"); + } + /// Serialises the tests that read or replace the process-global /// `RUNTIME_LIBRARY_PATH_ENV` while they run. Env is shared by every test /// thread, so a test that sets it and one that composes a child env from it @@ -5778,6 +5873,151 @@ mod tests { ); assert_eq!(name.as_deref(), Some("Planted 0.1")); } + + /// `os-release(5)` falls back to `/usr/lib/os-release` when `/etc/os-release` + /// is absent. Both `rocm examine` reads must still answer from a host that + /// ships only the fallback path — a probe that stopped after the first + /// candidate would read as an unknown distro instead. + #[cfg(all(feature = "e2e-test-hooks", target_os = "linux"))] + #[test] + fn os_release_reads_fall_back_to_usr_lib_when_etc_is_absent() { + use crate::hardware_root::TEST_HOST_ROOT_ENV; + use crate::test_env::RestoredEnvVar; + + let root = std::env::temp_dir().join(format!( + "rocm-core-os-release-fallback-root-{}", + crate::test_support::unique_suffix() + )); + std::fs::create_dir_all(root.join("usr/lib")).expect("create planted /usr/lib"); + std::fs::write( + root.join("usr/lib/os-release"), + "ID='fallback'\nVERSION_ID='1.2'\nPRETTY_NAME='Fallback 1.2'\n", + ) + .expect("write planted os-release"); + + let (examined, name) = { + let _guard = crate::hardware_root::HOST_ROOT_TEST_LOCK + .lock() + .unwrap_or_else(std::sync::PoisonError::into_inner); + let _root = RestoredEnvVar::set(TEST_HOST_ROOT_ENV, &root); + let mut examined = Examination::default(); + probe_os(&mut examined); + (examined, crate::host_gpu::detect_distro_name()) + }; + std::fs::remove_dir_all(&root).ok(); + + assert_eq!( + ( + examined.distro_id.as_str(), + examined.distro_version.as_str() + ), + ("fallback", "1.2") + ); + assert_eq!(name.as_deref(), Some("Fallback 1.2")); + } + + /// Guards [`TRY_OS_RELEASE_FN`] against drifting from the copy embedded in + /// [`WSL_REMOTE_PROBE`]: the test below exercises the standalone constant, + /// so if a future edit touches one and not the other, this catches it + /// rather than the test silently proving the wrong logic. + #[test] + fn try_os_release_fn_is_embedded_in_the_wsl_remote_probe() { + assert!( + WSL_REMOTE_PROBE.contains(TRY_OS_RELEASE_FN), + "WSL_REMOTE_PROBE's os-release handling has drifted from the tested function" + ); + } + + /// The WSL remote probe's `try_os_release` shell function, run for real + /// under `/bin/sh` against temp-directory paths rather than the real + /// `/etc`: it sources the first path that exists, falling back to the + /// second only when the first is absent, matching `os-release(5)` and the + /// Rust-side `hardware_root::read_os_release`. + #[cfg(target_os = "linux")] + #[test] + fn try_os_release_sources_the_fallback_only_when_the_primary_is_absent() { + let dir = tempfile::tempdir().expect("create temp dir"); + let primary = dir.path().join("primary"); + let fallback = dir.path().join("fallback"); + std::fs::write(&fallback, "ID=fallback\n").expect("write fallback"); + + let script = format!("{TRY_OS_RELEASE_FN}\ntry_os_release \"$1\" \"$2\"\necho \"id=$ID\""); + let run = || { + std::process::Command::new("sh") + .arg("-c") + .arg(&script) + .arg("sh") + .arg(&primary) + .arg(&fallback) + .output() + .expect("run sh") + }; + + let before = run(); + assert_eq!( + String::from_utf8_lossy(&before.stdout).trim(), + "id=fallback", + "stderr: {}", + String::from_utf8_lossy(&before.stderr) + ); + + std::fs::write(&primary, "ID=primary\n").expect("write primary"); + let after = run(); + assert_eq!( + String::from_utf8_lossy(&after.stdout).trim(), + "id=primary", + "stderr: {}", + String::from_utf8_lossy(&after.stderr) + ); + } + + /// `[ -e "$1" ]` is an existence check, not a readability one: a primary + /// that exists but cannot be sourced (here, a directory in its place, the + /// same portable non-readable fixture the Rust-side test above uses) + /// must not fall through to the `elif` and source the fallback — that + /// would silently read a file that may not describe this host, matching + /// `hardware_root::read_os_release`'s own non-absence rule. + /// + /// This is deliberately a directory, not a permission-denied file: CI + /// commonly runs as root, where a `chmod 000` file is still readable, so + /// a mode-000 fixture would pass or fail depending on who runs it. A + /// directory fails to source for a different, root-safe reason ("is a + /// directory"), which is enough to prove this one claim — existence is + /// not readability — but is **not** the same failure mode as a genuinely + /// unreadable primary. Under `/bin/sh` (`dash` on Debian/Ubuntu), + /// sourcing a *permission-denied* file is a fatal shell-level error that + /// aborts the whole embedded script immediately, not just this function — + /// a materially different outcome than "`$ID` stays unset" and one this + /// test does not exercise. That abort-on-unreadable-primary behavior + /// predates the `/usr/lib/os-release` fallback this module adds; fixing + /// it is out of scope here (tracked as a possible follow-up, not a + /// blocker for the fallback itself). + #[cfg(target_os = "linux")] + #[test] + fn try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable() { + let dir = tempfile::tempdir().expect("create temp dir"); + let primary = dir.path().join("primary"); + let fallback = dir.path().join("fallback"); + std::fs::create_dir(&primary).expect("create primary as a directory"); + std::fs::write(&fallback, "ID=fallback\n").expect("write fallback"); + + let script = format!("{TRY_OS_RELEASE_FN}\ntry_os_release \"$1\" \"$2\"\necho \"id=$ID\""); + let output = std::process::Command::new("sh") + .arg("-c") + .arg(&script) + .arg("sh") + .arg(&primary) + .arg(&fallback) + .output() + .expect("run sh"); + + assert_eq!( + String::from_utf8_lossy(&output.stdout).trim(), + "id=", + "stderr: {}", + String::from_utf8_lossy(&output.stderr) + ); + } } /// Property tests for the driver-side text readers above; a child module so it diff --git a/crates/rocm-core/src/fix.rs b/crates/rocm-core/src/fix.rs index 8000da2d21..00b8b28dcc 100644 --- a/crates/rocm-core/src/fix.rs +++ b/crates/rocm-core/src/fix.rs @@ -746,7 +746,7 @@ const RECIPES: &[FixRecipe] = &[ needs_sudo: false, needs_reboot: false, needs_relogin: false, - verify: "grep VERSION_ID /etc/os-release", + verify: "f=/etc/os-release; [ -e \"$f\" ] || f=/usr/lib/os-release; grep VERSION_ID \"$f\" 2>/dev/null | head -1", notes: &[ "Distros install side by side, so the current one can stay until the new one is set up.", ], diff --git a/crates/rocm-core/src/hardware_root.rs b/crates/rocm-core/src/hardware_root.rs index 4fd460f870..86a5e3d9e2 100644 --- a/crates/rocm-core/src/hardware_root.rs +++ b/crates/rocm-core/src/hardware_root.rs @@ -15,7 +15,9 @@ //! - `procfs`: `/proc/version`, `/proc/cpuinfo`, `/proc/meminfo`, //! `/proc/cmdline`, `/proc/modules` (the fallback when `lsmod` cannot run) //! and `/proc/1/cgroup`; -//! - the `/etc/os-release` behind the distro name `rocm examine` reports; +//! - the `/etc/os-release` behind the distro fields and name `rocm examine` +//! reports, falling back to `/usr/lib/os-release` when the former is absent, +//! per `os-release(5)`; //! - the modprobe configuration directories `/etc/modprobe.d`, //! `/usr/lib/modprobe.d` and `/run/modprobe.d`; //! - the WSL plumbing: the `/usr/lib/wsl/lib` directory check and @@ -33,9 +35,10 @@ //! `LD_LIBRARY_PATH`; re-rooting it would put the simulated directory in front //! of a real loader. Programs the probes execute, such as `ldconfig`, stay on //! the real host too: a simulated root holds no binary to run. Every -//! package-manager plan reads the real `/etc/os-release` — the install hints in -//! `openmpi.rs`, and the driver, OpenMPI and runtime-library installs in the -//! `rocm` binary — because the commands it builds run against the real +//! package-manager plan reads the real `/etc/os-release` (with the same +//! `/usr/lib/os-release` fallback) — the OpenMPI, libatomic and libnuma install +//! hints in `openmpi.rs`, and the driver, OpenMPI and runtime-library installs +//! in the `rocm` binary — because the commands it builds run against the real //! machine. Process liveness under `/proc/` and `/dev/shm` sizing are //! about this process's environment, not the hardware. //! @@ -75,6 +78,32 @@ pub fn host_path(path: impl AsRef) -> PathBuf { host_path_under(hardware_root().as_deref(), path.as_ref()) } +/// [`host_path`], fixed to `&str`. +/// +/// [`read_os_release`]'s `resolve` parameter needs a concrete +/// `Fn(&str) -> PathBuf`, which a bare reference to the generic `host_path` +/// cannot satisfy (the borrow checker rejects it as "not general enough" +/// over the resolved lifetime), so every probe that must honour a simulated +/// root passes this instead of `|p| host_path(p)`. +#[must_use] +pub fn host_path_for_str(path: &str) -> PathBuf { + host_path(path) +} + +/// [`read_os_release`]'s `resolve` parameter for a caller that must always +/// read the real machine. +/// +/// Never routed through [`host_path`], because it builds a package-manager +/// plan or install hint that runs against the real host, so a simulated +/// host root must not choose its distro (see each caller's own doc comment +/// for why). A bare `PathBuf::from` is rejected the same way a bare +/// `host_path` is (see [`host_path_for_str`]), so every such caller passes +/// this instead of `|p| PathBuf::from(p)`. +#[must_use] +pub fn identity_path_for_str(path: &str) -> PathBuf { + PathBuf::from(path) +} + #[cfg(feature = "e2e-test-hooks")] fn hardware_root() -> Option { std::env::var_os(TEST_HOST_ROOT_ENV) @@ -110,6 +139,116 @@ fn host_path_under(root: Option<&Path>, path: &Path) -> PathBuf { } } +/// What reading `/etc/os-release` (falling back to `/usr/lib/os-release` per +/// `os-release(5)`) produced. +/// +/// Kept as three states, not collapsed to `Option`, so a caller can +/// name the file it actually read in a parse-error message (`Found`'s `path`) +/// and can tell "nothing to report" (`Absent`, the documented fallback +/// contract: a missing file is not a failure) apart from "something is +/// wrong" (`Unreadable`: a candidate exists but could not be read). Before +/// this distinction existed, every caller folded both into the same empty +/// text and reported a host with a merely-unreadable file as an unsupported +/// distribution. +#[derive(Debug)] +pub enum OsRelease { + /// Read from `path` (`/etc/os-release` or `/usr/lib/os-release`). + Found { path: &'static str, text: String }, + /// Neither candidate exists. + Absent, + /// `path` exists but could not be read, for a reason other than absence + /// (permission denied, a directory in its place, ...). + Unreadable { + path: &'static str, + error: std::io::Error, + }, +} + +impl OsRelease { + /// The text to parse: the file's contents when one was read, empty for + /// [`Self::Absent`] or [`Self::Unreadable`] — an absent file declares + /// nothing, and an unreadable one must be reported as itself by the + /// caller rather than parsed as an empty, unknown distribution. + #[must_use] + pub fn text(&self) -> &str { + match self { + Self::Found { text, .. } => text, + Self::Absent | Self::Unreadable { .. } => "", + } + } + + /// The path a parse-error message should name: the one actually read, or + /// `/etc/os-release` for [`Self::Absent`] — which never reaches such a + /// message, since empty text never fails to parse. + #[must_use] + pub const fn path(&self) -> &'static str { + match self { + Self::Found { path, .. } | Self::Unreadable { path, .. } => path, + Self::Absent => "/etc/os-release", + } + } + + /// For tests: a [`Self::Found`] at the default `/etc/os-release` path. + #[cfg(test)] + pub(crate) fn found(text: impl Into) -> Self { + Self::Found { + path: "/etc/os-release", + text: text.into(), + } + } +} + +/// The shared opening every [`OsRelease::Unreadable`] message builds on. +/// +/// Names the candidate path and the I/O error that made it unreadable. Each +/// call site appends its own clause describing what that means for it (no +/// commands planned, a probe failure, an unreported distro, ...), so only +/// this shared part can drift if changed in one place and not another. +#[must_use] +pub fn unreadable_prefix(path: &str, error: &std::io::Error) -> String { + format!("{path} could not be read: {error}") +} + +/// Reads `/etc/os-release`, falling back to `/usr/lib/os-release` per +/// `os-release(5)` when the former is absent. +/// +/// `resolve` maps each candidate to where it should actually be read from — +/// [`host_path`] for a probe that must honour a simulated test root, or the +/// identity for one that must always read the real machine (see the module +/// doc above). +/// +/// Falls back only when `/etc/os-release` does not exist, never for another +/// read error (permission denied, a directory in its place, ...): `os-release(5)` +/// defines the fallback as existence-based, and treating any error the same +/// way would silently build commands for the wrong distro from a stale +/// `/usr/lib/os-release` on a host where `/etc/os-release` exists but is +/// merely unreadable. +pub fn read_os_release(resolve: impl Fn(&str) -> PathBuf) -> OsRelease { + match std::fs::read_to_string(resolve("/etc/os-release")) { + Ok(text) => OsRelease::Found { + path: "/etc/os-release", + text, + }, + Err(err) if err.kind() == std::io::ErrorKind::NotFound => { + match std::fs::read_to_string(resolve("/usr/lib/os-release")) { + Ok(text) => OsRelease::Found { + path: "/usr/lib/os-release", + text, + }, + Err(err) if err.kind() == std::io::ErrorKind::NotFound => OsRelease::Absent, + Err(error) => OsRelease::Unreadable { + path: "/usr/lib/os-release", + error, + }, + } + } + Err(error) => OsRelease::Unreadable { + path: "/etc/os-release", + error, + }, + } +} + /// Serialises every test that sets [`TEST_HOST_ROOT_ENV`], including the /// downstream probe test in `examine.rs`, so two of them never see each other's /// simulated root. @@ -182,4 +321,86 @@ mod tests { let _empty = crate::test_env::RestoredEnvVar::set(TEST_HOST_ROOT_ENV, Path::new("")); assert_eq!(host_path("/dev/kfd"), PathBuf::from("/dev/kfd")); } + + /// Maps `/etc/os-release` to `primary` and `/usr/lib/os-release` to + /// `fallback` under `dir`, so [`read_os_release`]'s fallback can be tested + /// without touching the real host's files. + fn candidate(dir: &Path, name: &str) -> PathBuf { + match name { + "/etc/os-release" => dir.join("primary"), + "/usr/lib/os-release" => dir.join("fallback"), + other => panic!("unexpected os-release candidate: {other}"), + } + } + + /// Extracts `(path, text)` from a [`OsRelease::Found`], panicking on any + /// other variant — the shape every "a candidate was read" assertion below + /// wants, written once so each test states only what differs. + fn found(read: OsRelease) -> (&'static str, String) { + match read { + OsRelease::Found { path, text } => (path, text), + other => panic!("expected OsRelease::Found, got {other:?}"), + } + } + + #[test] + fn read_os_release_prefers_the_primary_candidate() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::write(dir.path().join("primary"), "ID=primary\n").expect("write primary"); + std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); + assert_eq!( + found(read_os_release(|name| candidate(dir.path(), name))), + ("/etc/os-release", "ID=primary\n".to_owned()) + ); + } + + #[test] + fn read_os_release_falls_back_when_the_primary_is_absent() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); + assert_eq!( + found(read_os_release(|name| candidate(dir.path(), name))), + ("/usr/lib/os-release", "ID=fallback\n".to_owned()) + ); + } + + #[test] + fn read_os_release_is_absent_when_neither_candidate_exists() { + let dir = tempfile::tempdir().expect("create temp dir"); + assert!(matches!( + read_os_release(|name| candidate(dir.path(), name)), + OsRelease::Absent + )); + } + + /// A primary that exists but fails to read for a reason other than + /// absence (here, a directory in its place) must not fall back: that + /// would silently build commands for the wrong distro from a fallback + /// file that may not describe this host at all. A directory read as a + /// file is a portable, root-free way to get a non-`NotFound` `io::Error`. + /// It must also be reported as itself, not folded into `Absent`: an + /// unreadable file is not "nothing to report". + #[test] + fn read_os_release_does_not_fall_back_when_the_primary_errors_for_another_reason() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::create_dir(dir.path().join("primary")).expect("create primary as a directory"); + std::fs::write(dir.path().join("fallback"), "ID=fallback\n").expect("write fallback"); + match read_os_release(|name| candidate(dir.path(), name)) { + OsRelease::Unreadable { path, .. } => assert_eq!(path, "/etc/os-release"), + other => panic!("expected OsRelease::Unreadable, got {other:?}"), + } + } + + /// The same non-absence distinction, but on the fallback candidate: a + /// primary that is genuinely absent and a fallback that exists but + /// cannot be read must not read as `Absent` either. + #[test] + fn read_os_release_reports_the_fallback_as_unreadable_when_it_errors_for_another_reason() { + let dir = tempfile::tempdir().expect("create temp dir"); + std::fs::create_dir(dir.path().join("fallback")).expect("create fallback as a directory"); + match read_os_release(|name| candidate(dir.path(), name)) { + OsRelease::Unreadable { path, .. } => assert_eq!(path, "/usr/lib/os-release"), + other => panic!("expected OsRelease::Unreadable, got {other:?}"), + } + } } diff --git a/crates/rocm-core/src/host_gpu.rs b/crates/rocm-core/src/host_gpu.rs index c985ed5358..decd1a26ca 100644 --- a/crates/rocm-core/src/host_gpu.rs +++ b/crates/rocm-core/src/host_gpu.rs @@ -18,7 +18,7 @@ use crate::{ AppPaths, LegacyRocmSummary, TheRockFamilyManifest, detect_legacy_rocm_summary, - detect_managed_therock_family, discover_rocm_installs, examine, host_path, + detect_managed_therock_family, discover_rocm_installs, examine, hardware_root, host_path, managed_sdk_tool_path, runtime_is_linux, runtime_is_windows, runtime_os_name, unix_time_millis, }; use anyhow::Result; @@ -1968,28 +1968,38 @@ pub(crate) fn detect_distro_name() -> Option { } if runtime_is_linux() { - return Some(distro_name_from_os_release( - &fs::read_to_string(host_path("/etc/os-release")).ok()?, - )); + return match hardware_root::read_os_release(hardware_root::host_path_for_str) { + // Absent matches the pre-fallback behaviour this function has + // always had: no file at all leaves the distro name unknown + // entirely, rather than reporting "Linux" for a machine that + // might not even be running a standard distro. + hardware_root::OsRelease::Absent => None, + read => Some(distro_name_from_os_release(&read)), + }; } None } -/// The distribution name `rocm examine` prints, from os-release `text`: -/// `PRETTY_NAME` as `sh` reads it, else `Linux`. +/// The distribution name `rocm examine` prints, from `read`: `PRETTY_NAME` as +/// `sh` reads it, else `Linux`. /// -/// An unreadable file says which line made it so, on the line a person reads -/// — `rocm examine`'s `probe_failures`, which carries the same reason, is only -/// in the `--json` form. A blank `PRETTY_NAME` also falls back to `Linux`. -fn distro_name_from_os_release(text: &str) -> String { - match crate::os_release::parse(text) { +/// An unreadable line says which file and line made it so, on the line a +/// person reads — `rocm examine`'s `probe_failures`, which carries the same +/// reason, is only in the `--json` form. A blank `PRETTY_NAME` also falls +/// back to `Linux`. A file that exists but could not be read at all is +/// reported as itself, distinctly from a bad line it never reached. +fn distro_name_from_os_release(read: &hardware_root::OsRelease) -> String { + if let hardware_root::OsRelease::Unreadable { path, error } = read { + return format!("Linux ({})", hardware_root::unreadable_prefix(path, error)); + } + match crate::os_release::parse(read.text()) { Ok(mut fields) => fields .remove("PRETTY_NAME") .map(|value| value.trim().to_owned()) .filter(|value| !value.is_empty()) .unwrap_or_else(|| "Linux".to_owned()), - Err(unreadable) => format!("Linux (/etc/os-release {unreadable})"), + Err(unreadable) => format!("Linux ({} {unreadable})", read.path()), } } @@ -4787,7 +4797,9 @@ Class Name: Display #[test] fn parses_os_release_pretty_name() { assert_eq!( - distro_name_from_os_release("NAME=Ubuntu\nPRETTY_NAME=\"Ubuntu 24.04.2 LTS\"\n"), + distro_name_from_os_release(&hardware_root::OsRelease::found( + "NAME=Ubuntu\nPRETTY_NAME=\"Ubuntu 24.04.2 LTS\"\n" + )), "Ubuntu 24.04.2 LTS" ); } @@ -4800,17 +4812,59 @@ Class Name: Display #[test] fn pretty_name_reads_as_sh_reads_it() { assert_eq!( - distro_name_from_os_release( + distro_name_from_os_release(&hardware_root::OsRelease::found( "PRETTY_NAME=\"Debian GNU/Linux 12\"\nPRETTY_NAME='Ubuntu 24.04 LTS' # LTS\n" - ), + )), "Ubuntu 24.04 LTS" ); assert_eq!( - distro_name_from_os_release("PRETTY_NAME=\"Ubuntu 24.04 LTS\"\nunset ID\n"), + distro_name_from_os_release(&hardware_root::OsRelease::found( + "PRETTY_NAME=\"Ubuntu 24.04 LTS\"\nunset ID\n" + )), "Linux (/etc/os-release line 2 is not a plain assignment: \"unset ID\")" ); - assert_eq!(distro_name_from_os_release("PRETTY_NAME=\" \"\n"), "Linux"); - assert_eq!(distro_name_from_os_release("ID=ubuntu\n"), "Linux"); + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::found("PRETTY_NAME=\" \"\n")), + "Linux" + ); + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::found("ID=ubuntu\n")), + "Linux" + ); + } + + /// A file that exists but could not be read names itself and the error — + /// new behavior; it used to be folded into "unknown" like an absent file. + /// It is distinct from a bad line it never reached, and from "no file at + /// all", which `detect_distro_name` still reports as unknown (see its own + /// doc comment) — that part is unchanged. + #[test] + fn distro_name_names_an_unreadable_file_instead_of_guessing_linux() { + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }), + "Linux (/usr/lib/os-release could not be read: denied)" + ); + } + + /// The same malformed line as the second case in + /// [`pretty_name_reads_as_sh_reads_it`], but read through the fallback + /// path: the message must name `/usr/lib/os-release`, not + /// `/etc/os-release`. That test only exercises + /// [`hardware_root::OsRelease::found`], which hardcodes + /// `/etc/os-release`, so a regression that hardcoded the path back into + /// `distro_name_from_os_release`'s message would still pass it. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path() { + assert_eq!( + distro_name_from_os_release(&hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "PRETTY_NAME=\"Ubuntu 24.04 LTS\"\nunset ID\n".to_owned(), + }), + "Linux (/usr/lib/os-release line 2 is not a plain assignment: \"unset ID\")" + ); } #[test] diff --git a/crates/rocm-core/src/openmpi.rs b/crates/rocm-core/src/openmpi.rs index 953effd6f5..0d85299376 100644 --- a/crates/rocm-core/src/openmpi.rs +++ b/crates/rocm-core/src/openmpi.rs @@ -827,7 +827,16 @@ pub fn build_libnuma_install_plan(os_id: &str, id_like: &str) -> SystemPackageIn /// `ID_LIKE` to the plan that installs one runtime on it. pub type InstallPlanBuilder = fn(&str, &str) -> SystemPackageInstallPlan; -/// `build`'s plan for the distribution os-release `text` declares. +/// `build`'s plan for the distribution the os-release `text` at `path` +/// declares, naming `path` instead of always `/etc/os-release` in an +/// unreadable-line message. +/// +/// Unit tests that fixture bare `text` (never the real host) construct an +/// [`crate::hardware_root::OsRelease`] with +/// [`crate::hardware_root::OsRelease::found`] and call +/// [`plan_for_os_release_read`]; every production call site knows the real +/// path it read and calls this function or [`plan_for_os_release_read`] +/// directly. /// /// An unreadable file (see [`crate::os_release`]) plans nothing, and the /// reason names the line that made it unreadable and what to change on it, @@ -835,13 +844,17 @@ pub type InstallPlanBuilder = fn(&str, &str) -> SystemPackageInstallPlan; /// Without that, the plan would blame the distribution for what is a fixable /// line in the file. #[must_use] -pub fn plan_for_os_release(text: &str, build: InstallPlanBuilder) -> SystemPackageInstallPlan { +pub fn plan_for_os_release_at( + path: &str, + text: &str, + build: InstallPlanBuilder, +) -> SystemPackageInstallPlan { match crate::os_release::id_and_id_like(text) { Ok((os_id, id_like)) => build(&os_id, &id_like), Err(unreadable) => { let mut plan = build("", ""); plan.reason = format!( - "/etc/os-release {unreadable}, so the distribution cannot be read; to fix it, {}. {}", + "{path} {unreadable}, so the distribution cannot be read; to fix it, {}. {}", unreadable.fix(), plan.reason ); @@ -850,11 +863,40 @@ pub fn plan_for_os_release(text: &str, build: InstallPlanBuilder) -> SystemPacka } } +/// [`plan_for_os_release_at`] for `read`. +/// +/// Names the file actually read in an unreadable-line message, and reports a +/// file that exists but could not be read as itself rather than as an unknown +/// distribution. Without the latter, a host whose `/etc/os-release` is merely +/// unreadable (permission denied, a directory in its place) would say only +/// "Could not map distribution (ID=)" — the same message an actually unknown +/// distribution gets, sending the user looking for a support gap instead of +/// a filesystem problem. The real cause is now prepended ahead of that +/// generic message, not substituted for it — `build("", "")` still produces +/// it, since nothing else identifies the distribution either. +#[must_use] +pub fn plan_for_os_release_read( + read: &crate::hardware_root::OsRelease, + build: InstallPlanBuilder, +) -> SystemPackageInstallPlan { + if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { + let mut plan = build("", ""); + plan.reason = format!( + "{}, so the distribution cannot be read. {}", + crate::hardware_root::unreadable_prefix(path, error), + plan.reason + ); + return plan; + } + plan_for_os_release_at(read.path(), read.text(), build) +} + /// What a user missing a runtime is told to do, and whether the plan behind /// the advice installs anything. /// /// `rocm engines install vllm --yes` runs the same plan -/// ([`plan_for_os_release`] over the same builder and the same real file), so +/// ([`plan_for_os_release_read`] over the same builder and the same real +/// file), so /// a message may offer that command only when [`InstallHint::plan_installs`] /// is true; [`InstallHint::or`] does the offering. #[derive(Debug, Clone, PartialEq, Eq)] @@ -885,24 +927,43 @@ impl std::fmt::Display for InstallHint { } } -/// The hint for os-release `text`: the commands [`plan_for_os_release`] plans +/// The hint for os-release `text`, naming `/etc/os-release` in any +/// unreadable-line message: the commands [`plan_for_os_release_at`] plans /// with `build` when it plans any, otherwise `manual` — followed, for an /// unreadable file, by the line that made it so and what to change on it. -// Only the Linux hints read os-release at runtime; off Linux this is exercised -// solely by the cross-platform unit tests. -#[cfg_attr(not(target_os = "linux"), allow(dead_code))] +/// +/// Delegates to [`install_hint_for_at`]; only the cross-platform unit tests, +/// which fixture bare `text`, use this one — every production call site +/// knows the real path it read and calls [`install_hint_for_at`] or +/// [`install_hint_for_read`] directly. +#[cfg(test)] fn install_hint_for(text: &str, build: InstallPlanBuilder, manual: &str) -> InstallHint { + install_hint_for_at("/etc/os-release", text, build, manual) +} + +/// [`install_hint_for`], naming `path` instead of always `/etc/os-release` in +/// an unreadable-line message. +/// +/// Off Linux this has no non-test caller either — [`install_hint_for_read`], +/// its only production caller, is itself dead there for the same reason. +#[cfg_attr(not(target_os = "linux"), allow(dead_code))] +fn install_hint_for_at( + path: &str, + text: &str, + build: InstallPlanBuilder, + manual: &str, +) -> InstallHint { if let Err(unreadable) = crate::os_release::id_and_id_like(text) { return InstallHint { text: format!( - "{manual}; /etc/os-release {unreadable}, so the distribution cannot be read; \ + "{manual}; {path} {unreadable}, so the distribution cannot be read; \ to fix it, {}", unreadable.fix() ), plan_installs: false, }; } - let plan = plan_for_os_release(text, build); + let plan = plan_for_os_release_at(path, text, build); if plan.supported && !plan.commands.is_empty() { let rendered = plan .commands @@ -921,32 +982,37 @@ fn install_hint_for(text: &str, build: InstallPlanBuilder, manual: &str) -> Inst } } -/// [`install_hint`] for os-release `text`. -#[cfg_attr(not(target_os = "linux"), allow(dead_code))] -fn openmpi_install_hint_for(text: &str) -> InstallHint { - install_hint_for(text, build_openmpi_install_plan, OPENMPI_MANUAL_HINT) -} - -/// [`libatomic_install_hint`] for os-release `text`. -#[cfg_attr(not(target_os = "linux"), allow(dead_code))] -fn libatomic_install_hint_for(text: &str) -> InstallHint { - install_hint_for(text, build_libatomic_install_plan, LIBATOMIC_MANUAL_HINT) -} - -/// [`libnuma_install_hint`] for os-release `text`. +/// [`install_hint_for_at`] for `read`, naming the file actually read, and +/// reporting a file that exists but could not be read as itself rather than +/// as an unknown distribution — the same reasoning as +/// [`plan_for_os_release_read`], for the hint rather than the plan. #[cfg_attr(not(target_os = "linux"), allow(dead_code))] -fn libnuma_install_hint_for(text: &str) -> InstallHint { - install_hint_for(text, build_libnuma_install_plan, LIBNUMA_MANUAL_HINT) +fn install_hint_for_read( + read: &crate::hardware_root::OsRelease, + build: InstallPlanBuilder, + manual: &str, +) -> InstallHint { + if let crate::hardware_root::OsRelease::Unreadable { path, error } = read { + return InstallHint { + text: format!( + "{manual}; {}, so the distribution cannot be read", + crate::hardware_root::unreadable_prefix(path, error) + ), + plan_installs: false, + }; + } + install_hint_for_at(read.path(), read.text(), build, manual) } -/// The real host's `/etc/os-release`, empty when it cannot be read. +/// The real host's `/etc/os-release`, falling back to `/usr/lib/os-release` +/// when the former is absent (per `os-release(5)`). /// /// Not routed through [`crate::host_path`]: the hints name package-manager /// commands for the real machine, so a simulated host root must not choose /// their distribution. #[cfg(target_os = "linux")] -fn real_os_release() -> String { - std::fs::read_to_string("/etc/os-release").unwrap_or_default() +fn real_os_release() -> crate::hardware_root::OsRelease { + crate::hardware_root::read_os_release(crate::hardware_root::identity_path_for_str) } const OPENMPI_MANUAL_HINT: &str = "install your distribution's OpenMPI runtime package (providing libmpi.so / libmpi_cxx.so and mpirun)"; @@ -958,7 +1024,8 @@ const LIBNUMA_MANUAL_HINT: &str = /// Build a short, distro-aware hint describing how to install the OpenMPI /// runtime that vLLM requires, for embedding in user-facing error messages. /// -/// On Linux it reads `/etc/os-release` and returns the package-manager command +/// On Linux it reads `/etc/os-release` (falling back to `/usr/lib/os-release` +/// per `os-release(5)`) and returns the package-manager command /// from [`build_openmpi_install_plan`] when the distribution is recognized, /// otherwise a generic instruction. Off Linux it returns a generic message, /// since the OpenMPI path is not exercised there. @@ -967,7 +1034,11 @@ const LIBNUMA_MANUAL_HINT: &str = pub fn install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - openmpi_install_hint_for(&real_os_release()) + install_hint_for_read( + &real_os_release(), + build_openmpi_install_plan, + OPENMPI_MANUAL_HINT, + ) } #[cfg(not(target_os = "linux"))] { @@ -981,7 +1052,8 @@ pub fn install_hint() -> InstallHint { /// Build a short, distro-aware hint describing how to install the `libatomic` /// runtime that vLLM requires, for embedding in user-facing error messages. /// -/// On Linux it reads `/etc/os-release` and returns the package-manager command +/// On Linux it reads `/etc/os-release` (falling back to `/usr/lib/os-release` +/// per `os-release(5)`) and returns the package-manager command /// from [`build_libatomic_install_plan`] when the distribution is recognized, /// otherwise a generic instruction. Off Linux it returns a generic message. /// [`InstallHint::or`] offers an automatic install only when that plan @@ -989,7 +1061,11 @@ pub fn install_hint() -> InstallHint { pub fn libatomic_install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - libatomic_install_hint_for(&real_os_release()) + install_hint_for_read( + &real_os_release(), + build_libatomic_install_plan, + LIBATOMIC_MANUAL_HINT, + ) } #[cfg(not(target_os = "linux"))] { @@ -1003,7 +1079,8 @@ pub fn libatomic_install_hint() -> InstallHint { /// Build a short, distro-aware hint describing how to install the real `libnuma` /// runtime that PyTorch requires, for embedding in user-facing error messages. /// -/// On Linux it reads `/etc/os-release` and returns the package-manager command +/// On Linux it reads `/etc/os-release` (falling back to `/usr/lib/os-release` +/// per `os-release(5)`) and returns the package-manager command /// from [`build_libnuma_install_plan`] when the distribution is recognized, /// otherwise a generic instruction. Off Linux it returns a generic message. /// [`InstallHint::or`] offers an automatic install only when that plan @@ -1011,7 +1088,11 @@ pub fn libatomic_install_hint() -> InstallHint { pub fn libnuma_install_hint() -> InstallHint { #[cfg(target_os = "linux")] { - libnuma_install_hint_for(&real_os_release()) + install_hint_for_read( + &real_os_release(), + build_libnuma_install_plan, + LIBNUMA_MANUAL_HINT, + ) } #[cfg(not(target_os = "linux"))] { @@ -1233,7 +1314,7 @@ mod tests { ("ID=derivative\nID_LIKE=\"rhel fedora\"\n", &dnf), ] { assert_eq!( - &plan_for_os_release(text, build), + &plan_for_os_release_read(&crate::hardware_root::OsRelease::found(text), build), expected, "{label}: {text:?}" ); @@ -1258,41 +1339,133 @@ mod tests { } } - /// Each public hint uses its own runtime's builder and manual advice: - /// the three wrappers, against fixed text rather than the host's file. + /// Each public hint uses its own runtime's builder and manual advice, + /// against fixed text rather than the host's file. #[test] fn each_hint_names_its_own_runtime() { let apt = |packages: &str| { format!("install it with `sudo apt-get update && sudo apt-get install -y {packages}`") }; assert_eq!( - openmpi_install_hint_for("ID=ubuntu\n").text, + install_hint_for( + "ID=ubuntu\n", + build_openmpi_install_plan, + OPENMPI_MANUAL_HINT + ) + .text, apt("openmpi-bin libopenmpi-dev") ); assert_eq!( - libatomic_install_hint_for("ID=ubuntu\n").text, + install_hint_for( + "ID=ubuntu\n", + build_libatomic_install_plan, + LIBATOMIC_MANUAL_HINT + ) + .text, apt("libatomic1") ); assert_eq!( - libnuma_install_hint_for("ID=ubuntu\n").text, + install_hint_for( + "ID=ubuntu\n", + build_libnuma_install_plan, + LIBNUMA_MANUAL_HINT + ) + .text, apt("libnuma1") ); // And each one's own manual advice for a distribution it cannot map. assert_eq!( - openmpi_install_hint_for("ID=plan9\n").text, + install_hint_for( + "ID=plan9\n", + build_openmpi_install_plan, + OPENMPI_MANUAL_HINT + ) + .text, "install your distribution's OpenMPI runtime package \ (providing libmpi.so / libmpi_cxx.so and mpirun)" ); assert_eq!( - libatomic_install_hint_for("ID=plan9\n").text, + install_hint_for( + "ID=plan9\n", + build_libatomic_install_plan, + LIBATOMIC_MANUAL_HINT + ) + .text, "install your distribution's libatomic runtime package (providing libatomic.so.1)" ); assert_eq!( - libnuma_install_hint_for("ID=plan9\n").text, + install_hint_for( + "ID=plan9\n", + build_libnuma_install_plan, + LIBNUMA_MANUAL_HINT + ) + .text, "install your distribution's numactl runtime package (providing libnuma.so.1)" ); } + /// [`install_hint_for_read`] and [`plan_for_os_release_read`] report a + /// file that exists but could not be read as itself, not as an unknown + /// distribution — the gap `install_hint_for`/`plan_for_os_release_at` + /// alone cannot close, since by the time they see `text` the distinction + /// between "absent" and "unreadable" is already lost. + #[test] + fn an_unreadable_file_is_reported_as_itself_not_an_unknown_distribution() { + let read = crate::hardware_root::OsRelease::Unreadable { + path: "/usr/lib/os-release", + error: std::io::Error::new(std::io::ErrorKind::PermissionDenied, "denied"), + }; + let hint = install_hint_for_read(&read, build_openmpi_install_plan, OPENMPI_MANUAL_HINT); + assert_eq!( + hint.text, + format!( + "{OPENMPI_MANUAL_HINT}; /usr/lib/os-release could not be read: denied, so the \ + distribution cannot be read" + ) + ); + assert!(!hint.plan_installs); + + let plan = plan_for_os_release_read(&read, build_openmpi_install_plan); + assert!(!plan.supported); + assert!(plan.commands.is_empty()); + assert!( + plan.reason + .starts_with("/usr/lib/os-release could not be read: denied"), + "{}", + plan.reason + ); + } + + /// `install_hint_for_read`/`plan_for_os_release_read` are the one seam + /// `openmpi::real_os_release()` and `runtime_install_finalize::real_os_release()` + /// hand their result to — both now one-line delegations to + /// `hardware_root::read_os_release`, so reverting either back to a raw + /// `/etc/os-release` read is a type error here, not a silent regression. + /// This still pins the behaviour at the seam itself: an `OsRelease` that + /// says the fallback path was read produces the same plan and hint a + /// primary-path read with the same content would. + #[test] + fn a_fallback_read_plans_and_hints_exactly_like_a_primary_read() { + let fallback = crate::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\n".to_owned(), + }; + let primary = crate::hardware_root::OsRelease::found("ID=ubuntu\n"); + + assert_eq!( + plan_for_os_release_read(&fallback, build_openmpi_install_plan), + plan_for_os_release_read(&primary, build_openmpi_install_plan), + ); + assert_eq!( + install_hint_for_read(&fallback, build_openmpi_install_plan, OPENMPI_MANUAL_HINT), + install_hint_for_read(&primary, build_openmpi_install_plan, OPENMPI_MANUAL_HINT), + ); + assert_eq!( + install_hint_for_read(&fallback, build_openmpi_install_plan, OPENMPI_MANUAL_HINT).text, + "install it with `sudo apt-get update && sudo apt-get install -y openmpi-bin libopenmpi-dev`" + ); + } + /// The message and the plan it describes, together: an unreadable file /// plans nothing, and both the plan's reason and the hint name the line /// and what to change on it, rather than blaming an unknown distribution. @@ -1302,7 +1475,8 @@ mod tests { fn an_unreadable_file_plans_nothing_and_names_its_line() { let text = "ID=ubuntu\nexport ID=debian\n"; for (label, build, manual) in BUILDERS { - let plan = plan_for_os_release(text, build); + let plan = + plan_for_os_release_read(&crate::hardware_root::OsRelease::found(text), build); assert!(!plan.supported, "{label}"); assert_eq!(plan.package_manager, None, "{label}"); assert!(plan.commands.is_empty(), "{label}"); @@ -1333,6 +1507,49 @@ mod tests { } } + /// The same malformed line as + /// [`an_unreadable_file_plans_nothing_and_names_its_line`], but read + /// through the fallback path: both the plan's reason and the hint must + /// name `/usr/lib/os-release`, not `/etc/os-release`. Every malformed-line + /// test before this one went through either the bare, hardcoded-`/etc` + /// functions or [`crate::hardware_root::OsRelease::found`] (which also + /// hardcodes `/etc/os-release`), so a regression that hardcoded the path + /// back into `plan_for_os_release_read`/`install_hint_for_read` would + /// have passed every one of them. + #[test] + fn a_fallback_reads_malformed_line_names_the_fallback_path() { + let read = crate::hardware_root::OsRelease::Found { + path: "/usr/lib/os-release", + text: "ID=ubuntu\nexport ID=debian\n".to_owned(), + }; + for (label, build, manual) in BUILDERS { + let plan = plan_for_os_release_read(&read, build); + assert!(!plan.supported, "{label}"); + assert!( + plan.reason.starts_with( + "/usr/lib/os-release line 2 is not a plain assignment: \ + \"export ID=debian\", so the distribution cannot be read; to fix \ + it, remove that line or rewrite it as NAME=value. Could not map \ + distribution" + ), + "{label}: {}", + plan.reason + ); + + let hint = install_hint_for_read(&read, build, manual); + assert_eq!( + hint.text, + format!( + "{manual}; /usr/lib/os-release line 2 is not a plain assignment: \ + \"export ID=debian\", so the distribution cannot be read; to fix it, \ + remove that line or rewrite it as NAME=value" + ), + "{label}" + ); + assert!(!hint.plan_installs, "{label}"); + } + } + /// An automatic install is offered exactly when the plan it would run /// installs something: for a recognised distribution, and not for an /// unknown one or an unreadable file. @@ -1345,7 +1562,8 @@ mod tests { "ID=ubuntu\nNAME=a b\n", "ID=ubuntu\r\n", ] { - let plan = plan_for_os_release(text, build); + let plan = + plan_for_os_release_read(&crate::hardware_root::OsRelease::found(text), build); let hint = install_hint_for(text, build, manual); let offered = hint.or("rerun with --yes"); let installs = plan.supported && !plan.commands.is_empty(); diff --git a/docs/release-trust.md b/docs/release-trust.md index 3bb57583ed..b5d4429b9b 100644 --- a/docs/release-trust.md +++ b/docs/release-trust.md @@ -317,7 +317,8 @@ under `/sys/class/kfd`, the DRM cards under `/sys/class/drm`, `/sys/module/amdgpu` and its `version` file, `/proc/version`, `/proc/cpuinfo`, `/proc/meminfo`, `/proc/cmdline`, `/proc/modules`, `/proc/1/cgroup`, the container markers `/.dockerenv` and `/run/.containerenv`, the `/etc/os-release` -behind the distro fields and name `rocm examine` reports, the modprobe +(falling back to `/usr/lib/os-release` when absent, per `os-release(5)`) behind +the distro fields and name `rocm examine` reports, the modprobe configuration directories `/etc/modprobe.d`, `/usr/lib/modprobe.d` and `/run/modprobe.d`, the WSL plumbing under `/usr/lib/wsl` (the `lib` directory and `lib/libdxcore.so`), and the WSL ROCDXG capability check, which looks for @@ -350,11 +351,11 @@ Some reads stay on the real machine even in a hook build: two files under each discovered install's path inside the simulated root. - The `/usr/lib/wsl/lib` loader entry an engine is launched with, and programs the probes execute, such as `ldconfig`. -- Every package-manager plan, which reads the real `/etc/os-release`: the - OpenMPI, libatomic and libnuma install hints, and the driver, OpenMPI and - runtime-library installs `rocm` runs before serving. Their commands run - against the real machine, so a simulated host must not pick the distro they - are built for. +- Every package-manager plan, which reads the real `/etc/os-release` (with the + same `/usr/lib/os-release` fallback): the OpenMPI, libatomic and libnuma + install hints, and the driver, OpenMPI and runtime-library installs `rocm` + runs before serving. Their commands run against the real machine, so a + simulated host must not pick the distro they are built for. - Process liveness under `/proc/` and `/dev/shm` sizing. Both describe this process's own environment, not the hardware. diff --git a/docs/testing.md b/docs/testing.md index c63f379ef4..cc1f70b4a2 100644 --- a/docs/testing.md +++ b/docs/testing.md @@ -1610,54 +1610,127 @@ and the distro name it prints `rocm diagnose --distro` run from Windows, which has the WSL distribution's own `sh` source the file and reports what it assigned. +Every one of those readers except the WSL remote probe above goes through +[`hardware_root::read_os_release`](../crates/rocm-core/src/hardware_root.rs), +which reads `/etc/os-release` and, if that file does not exist, falls back to +`/usr/lib/os-release` per `os-release(5)` — a file present but unreadable (the +line-reporting cases below, and the file-level case further down) does not +fall back, since a stale fallback could describe the wrong host entirely. +The two reads it covers: a probe routed through a simulated test root +(`rocm examine`'s distro fields and distro name) resolves both candidates +through `host_path`; a package-manager plan (the driver install, and the +OpenMPI/libatomic/libnuma installs and hints) always resolves both against the +real machine, for the same reason it never follows a simulated root at all. +Each production call site is a one-line delegation to this shared reader, so +it names the candidate it actually read — `/etc/os-release` or +`/usr/lib/os-release` — rather than always the former, in every message below. + A line that is not a plain assignment makes the whole file unreadable, and -each reader names that line instead of reporting an unknown distro. Where the -message asks for a fix, it also says what to change on the line: LF line -endings, single quotes around the value, or a `NAME=value` line in place of -anything else. +each reader names that file and line instead of reporting an unknown distro. +Where the message asks for a fix, it also says what to change on the line: LF +line endings, single quotes around the value, or a `NAME=value` line in place +of anything else. - `rocm install driver`: policy `unreadable_os_release`, no commands, and a - reason naming the line. -- The OpenMPI, libatomic and libnuma installs: no commands, and the line ahead - of the manual-install advice in the plan's reason. -- The hints naming those installs in vLLM's warnings and errors: the line - after the manual-install advice, and no offer of `rocm engines install vllm - --yes`, which would plan nothing. That command is offered only when its plan - has commands, so it is not offered for an unknown distribution either. + reason naming the file and line. +- The OpenMPI, libatomic and libnuma installs: no commands, and the file and + line ahead of the manual-install advice in the plan's reason. +- The hints naming those installs in vLLM's warnings and errors: the file and + line after the manual-install advice, and no offer of `rocm engines install + vllm --yes`, which would plan nothing. That command is offered only when its + plan has commands, so it is not offered for an unknown distribution either. - `rocm examine`: `distro: Linux (/etc/os-release line N is not a plain assignment: "…")`; with `--json`, also an empty `distro_id` and - `distro_version`, the same line in `probe_failures`, and `status: degraded` - on an otherwise healthy GPU host. + `distro_version`, the same file and line in `probe_failures`, and `status: + degraded` on an otherwise healthy GPU host. A CRLF file is unreadable too: `sh` would assign `ubuntu\r`. +A candidate that exists but cannot be read at all (permission denied, a +directory in its place) is reported distinctly from both of the above: not as +an unknown distribution (which would send the user looking for a support +matrix for what is a filesystem problem) and not folded into "absent, so fall +back to the other candidate" (which could silently plan from a stale file that +may not describe this host). This is `hardware_root::OsRelease`, the fallback +reader's return type: `Found { path, text }` for a successful read (naming +whichever candidate it was), `Absent` when neither candidate exists (not a +failure; a missing file declares nothing), or `Unreadable { path, error }` +when a candidate exists but could not be read. Every production call site +above matches on all three: `rocm install driver` via +`build_driver_install_plan_read`, the OpenMPI/libatomic/libnuma installs and +hints via `plan_for_os_release_read`/`install_hint_for_read`, and `rocm +examine`'s distro fields and distro name via `record_distro` and +`distro_name_from_os_release`, which both take the whole `OsRelease` directly. +The three `_read`-suffixed functions are the one seam the real call site +hands its result to, and each delegates to the matching `_at` function with +the path it actually read. `install_hint_for`/`build_driver_install_plan` +are bare-text siblings of `_at` — not something `_read` delegates through — +kept only for the unit tests below, which fixture text directly and have no +`OsRelease` of their own to construct. + ```bash cargo test -p rocm-core --lib os_release cargo test -p rocm-core --lib -- pretty_name_reads_as_sh_reads_it an_unreadable_os_release cargo test -p rocm-core --lib openmpi::tests cargo test -p rocm --bin rocm os_release -cargo test -p rocm-core --lib --features e2e-test-hooks os_release_reads_follow_the_simulated_host_root -``` - -The parser tests that compare against `/bin/sh` itself are Linux-only. The last -command plants a file under the simulated host root and checks that both -`rocm examine` reads answer from it through the shared parser; the feature it -needs is enabled only by its own CI step. +cargo test -p rocm --bin rocm -- a_fallback_read_plans an_unreadable_file_plans_nothing_and_names_itself +cargo test -p rocm-core --lib hardware_root::tests::read_os_release +cargo test -p rocm-core --lib -- a_fallback_read_plans an_unreadable_file_is_reported_as_itself distro_name_names_an_unreadable_file an_unreadable_file_names_itself +cargo test -p rocm-core --lib --features e2e-test-hooks -- os_release_reads_follow_the_simulated_host_root os_release_reads_fall_back_to_usr_lib_when_etc_is_absent try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable +``` + +The parser tests that compare against `/bin/sh` itself are Linux-only. The +`hardware_root::tests::read_os_release*` tests check the fallback itself +(primary found, primary absent, neither found, and each candidate existing but +erroring for a reason other than absence) against an injected temp directory +rather than the real host. The `a_fallback_read_plans*`/ +`an_unreadable_file*`/`distro_name_names_an_unreadable_file` tests in +`rocm-core` and `rocm` construct an `OsRelease` directly — bypassing the real +read entirely, since the production functions that do it +(`openmpi::real_os_release`, `runtime_install_finalize::real_os_release`) +read the real machine +unconditionally and cannot honour a simulated root — to pin that a +fallback-sourced read plans and hints identically to a primary-sourced one +with the same text, and that a file which exists but cannot be read is named +as itself rather than silently treated as an unknown distribution. The two +`--features e2e-test-hooks` os-release tests plant a file under the simulated +host root and check that both `rocm examine` reads answer from it through the +shared parser: the first at `/etc/os-release`, the second with only +`/usr/lib/os-release` present, so the fallback is exercised through the real +`host_path`-routed call sites, not just the helper in isolation; the feature +they need is enabled only by its own CI step. The +`try_os_release_does_not_source_the_fallback_when_the_primary_is_not_sourceable` +test runs the WSL remote probe's own shell fallback for real under `/bin/sh` +against a primary that exists but cannot be sourced (a directory in its +place) — proving existence is not readability, the same claim the Rust-side +`hardware_root` tests make for the two in-process readers, but **not** the +same failure mode: a genuinely permission-denied primary aborts the whole +shell probe instead of merely leaving `$ID` unset, which this test does not +exercise — see its own doc comment for why, and for the known limitation +this leaves. `rocm examine` reads the file through the simulated host root (see Simulated Host Root in [release-trust.md](release-trust.md)), so scenarios -`examine-20` to `examine-23` in -[examine.feature](../tests/e2e-cucumber/features/examine.feature) plant one. -`examine-23` also plants a GPU in the kernel topology and puts an `lspci` -listing an empty bus on `PATH`, so `status: degraded` is checked on every Linux -lane, with or without a GPU: +`examine-20` to `examine-23` and `examine-27` to `examine-28` in +[examine.feature](../tests/e2e-cucumber/features/examine.feature) plant one +(`examine-24` to `examine-26` are unrelated amd-smi telemetry scenarios that +share this file's numbering). `examine-23` also plants a GPU in the kernel +topology and puts an `lspci` listing an empty bus on `PATH`, so `status: +degraded` is checked on every Linux lane, with or without a GPU. `examine-27` +plants only `/usr/lib/os-release`, with no `/etc/os-release` present, to check +the `os-release(5)` fallback. `examine-28` plants a directory in place of +`/etc/os-release` (reusing `examine-23`'s GPU fixtures) to check the degraded +verdict and failure message a present-but-unreadable release file now gets, +distinctly from both a malformed line and an unknown distribution: ```bash -RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-2[0-3] ' +RUSTC_WRAPPER= cargo xtask e2e -- -n 'examine-2[0-3] |examine-2[7-8] ' ``` The install plans deliberately read the real file, so no scenario plants one -for them; their parsing is covered by the unit tests above. +for them, including for the fallback; their parsing is covered by the unit +tests above, and the fallback itself by `hardware_root`'s own unit tests, +since both now read through the same helper with an identity resolver. ## Windows Runtime Preflight diff --git a/tests/e2e-cucumber/features/examine.feature b/tests/e2e-cucumber/features/examine.feature index 5d96a15a85..00c62c3f37 100644 --- a/tests/e2e-cucumber/features/examine.feature +++ b/tests/e2e-cucumber/features/examine.feature @@ -282,7 +282,7 @@ Feature: GPU detection and system inspection # `cargo xtask e2e` and every prebuilt full-suite lane use), so they describe a # machine other than the runner. The driver plan cannot be exercised this way: # `rocm install driver` builds a plan that runs against the real machine, so it - # deliberately reads the real `/etc/os-release` (see `read_os_release`); its + # deliberately reads the real `/etc/os-release` (see `real_os_release`); its # parsing is covered by the unit tests in `driver_install.rs`. # # The planted distributions are ones no CI runner or developer host here runs, @@ -404,3 +404,27 @@ Feature: GPU detection and system inspection Given amd-smi answers the first probe and then stalls on the second When the daemon gathers a bridge snapshot Then the snapshot keeps the first probe's GPUs and explains the second with a bounded note naming the timeout + + # `os-release(5)` says to read `/etc/os-release` and, if it does not exist, + # fall back to `/usr/lib/os-release`. This plants a simulated host root with + # only the fallback path populated, so a reader that stopped after the first + # candidate would see no file at all and report an unknown distribution. + @id:examine-falls-back-to-usr-lib-os-release @requires-os:linux + Scenario: examine-27 - The inspection falls back to /usr/lib/os-release when /etc/os-release is absent + Given a machine whose release file exists only at /usr/lib/os-release + When the user inspects that machine in machine-readable form + Then the inspection reports the distribution "ubuntu" version "24.04" named "Ubuntu 24.04 LTS" + And the inspection reports no trouble reading the release file + + # Before this change, a release file that exists but cannot be read (not + # absent, so no fallback candidate is tried either) silently produced an + # empty, unreported distro with no failure recorded. It now reports the + # file as itself, distinctly from both an unknown distribution and a + # malformed line it never reached. A directory in place of the file is a + # non-`NotFound` read error that needs no root privilege, unlike a + # mode-000 file, which CI running as root would read anyway. + @id:examine-degrades-on-unreadable-release-file @requires-os:linux + Scenario: examine-28 - An unreadable release file degrades the verdict on a machine with a GPU + Given a GPU machine whose release file cannot be read + When the user inspects that machine in machine-readable form + Then the inspection's verdict is degraded, and its only failure says the release file could not be read diff --git a/tests/e2e-cucumber/tests/e2e/examine_steps.rs b/tests/e2e-cucumber/tests/e2e/examine_steps.rs index 8b4453077d..95f0344aaf 100644 --- a/tests/e2e-cucumber/tests/e2e/examine_steps.rs +++ b/tests/e2e-cucumber/tests/e2e/examine_steps.rs @@ -1343,6 +1343,32 @@ fn plant_os_release(world: &mut E2eWorld, body: &str) { .push(("ROCM_CLI_TEST_HOST_ROOT", root.into_os_string())); } +/// Plant `body` as `/usr/lib/os-release` under a simulated host root, with no +/// `/etc/os-release` present — the fallback `os-release(5)` defines, and the +/// one `plant_os_release` above does not exercise. +fn plant_os_release_fallback_only(world: &mut E2eWorld, body: &str) { + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("host-root"); + std::fs::create_dir_all(root.join("usr/lib")).expect("failed to create planted /usr/lib"); + std::fs::write(root.join("usr/lib").join("os-release"), body) + .expect("failed to write planted os-release"); + world + .command_env + .push(("ROCM_CLI_TEST_HOST_ROOT", root.into_os_string())); +} + +#[given("a machine whose release file exists only at /usr/lib/os-release")] +async fn os_release_only_at_usr_lib(world: &mut E2eWorld) { + plant_os_release_fallback_only( + world, + "NAME=\"Ubuntu\"\nID=ubuntu\nVERSION_ID=\"24.04\"\nPRETTY_NAME=\"Ubuntu 24.04 LTS\"\n", + ); +} + #[given("a machine whose release file quotes every value in single quotes")] async fn os_release_single_quoted(world: &mut E2eWorld) { plant_os_release( @@ -1373,17 +1399,20 @@ async fn os_release_with_a_command(world: &mut E2eWorld) { const RUNS_A_COMMAND_ON_LINE_3: &str = "ID=ubuntu\nVERSION_ID=\"24.04\"\nexport ID=debian\nPRETTY_NAME=\"Ubuntu 24.04 LTS\"\n"; -#[given("a GPU machine whose release file runs a command on line 3")] -async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { - plant_os_release(world, RUNS_A_COMMAND_ON_LINE_3); +/// One GPU node in the kernel topology: a gfx1101 with no PCI address, so it +/// matches no `lspci` entry and is listed from the topology alone. Plus an +/// `lspci` that lists an empty bus, ahead of any real one, so the PCI probe +/// succeeds on every runner without describing the runner's cards. +/// +/// Used by every scenario that needs a verdict to degrade *from* — without a +/// GPU, the verdict is `no-amd-gpu` whatever the release file says. +fn plant_gpu_fixtures(world: &mut E2eWorld) { let root = world .isolated_root .as_ref() .expect("no isolated root") .path() .to_owned(); - // One GPU node in the kernel topology: a gfx1101 with no PCI address, so it - // matches no `lspci` entry and is listed from the topology alone. let node = root.join("host-root/sys/class/kfd/kfd/topology/nodes/1"); std::fs::create_dir_all(&node).expect("failed to create planted KFD node"); std::fs::write( @@ -1391,8 +1420,6 @@ async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { "cpu_cores_count 0\nsimd_count 120\ngfx_target_version 110001\n", ) .expect("failed to write planted KFD node properties"); - // An `lspci` that lists an empty bus, ahead of any real one, so the PCI - // probe succeeds on every runner without describing the runner's cards. let bin = root.join("fake-bin"); std::fs::create_dir_all(&bin).expect("failed to create the fake PATH dir"); rocm_core::fake_executable::write_fake_executable(&bin.join("lspci"), "#!/bin/sh\nexit 0\n") @@ -1404,6 +1431,32 @@ async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { world.command_env.push(("PATH", path)); } +#[given("a GPU machine whose release file runs a command on line 3")] +async fn gpu_machine_with_unreadable_os_release(world: &mut E2eWorld) { + plant_os_release(world, RUNS_A_COMMAND_ON_LINE_3); + plant_gpu_fixtures(world); +} + +/// A directory in place of the file is a non-`NotFound` read error that needs +/// no root privilege — unlike a mode-000 file, which CI running as root would +/// read anyway — the same portable fixture the `hardware_root` and WSL-probe +/// unit tests use for "exists but errors". +#[given("a GPU machine whose release file cannot be read")] +async fn gpu_machine_with_unreadable_release_file(world: &mut E2eWorld) { + let root = world + .isolated_root + .as_ref() + .expect("no isolated root") + .path() + .join("host-root"); + std::fs::create_dir_all(root.join("etc/os-release")) + .expect("failed to create planted os-release directory"); + world + .command_env + .push(("ROCM_CLI_TEST_HOST_ROOT", root.into_os_string())); + plant_gpu_fixtures(world); +} + #[when("the user inspects that machine in machine-readable form")] async fn user_inspects_planted_machine(world: &mut E2eWorld) { let (stdout, stderr, rc) = @@ -1420,13 +1473,19 @@ fn inspection_str<'a>(json: &'a serde_json::Value, pointer: &str) -> &'a str { } /// The `probe_failures` entries that are about the release file. +/// +/// Matches either candidate path: every failure message names the file +/// actually read (`/etc/os-release` or, on a fallback-only host, +/// `/usr/lib/os-release`), so a filter that only matched the former would +/// silently drop a release-file failure on a fallback-only host before any +/// assertion below ever saw it. fn os_release_failures(json: &serde_json::Value) -> Vec { json.get("probe_failures") .and_then(serde_json::Value::as_array) .unwrap_or_else(|| panic!("`examine --json` has no probe_failures array:\n{json:#}")) .iter() .filter_map(serde_json::Value::as_str) - .filter(|failure| failure.contains("/etc/os-release")) + .filter(|failure| failure.contains("os-release")) .map(str::to_owned) .collect() } @@ -1489,6 +1548,34 @@ async fn assert_degraded_by_os_release_alone(world: &mut E2eWorld, line: u32) { ); } +#[then( + expr = "the inspection's verdict is degraded, and its only failure says the release file could not be read" +)] +async fn assert_degraded_by_unreadable_os_release(world: &mut E2eWorld) { + assert_eq!(world.cli_rc, Some(0), "`rocm examine --json` failed"); + let json = parsed_json(world); + // The GPU is what lets the verdict be `degraded` rather than `no-amd-gpu`. + assert_eq!( + json.get("has_amd_gpu").and_then(serde_json::Value::as_bool), + Some(true), + "the planted GPU was not found:\n{json:#}" + ); + assert_eq!( + inspection_str(&json, &format!("/{VERDICT_FIELD}")), + "degraded", + "{json:#}" + ); + let failures = os_release_failures(&json); + assert_eq!(failures.len(), 1, "{json:#}"); + // Not an exact match on the OS's read-error text (e.g. "Is a directory + // (os error 21)" on Linux), which this test does not mean to pin. + assert!( + failures[0].starts_with("/etc/os-release could not be read: ") + && failures[0].ends_with("; the distro is not reported."), + "{json:#}" + ); +} + #[then("the inspection reports no distribution")] async fn assert_no_distribution(world: &mut E2eWorld) { assert_eq!(world.cli_rc, Some(0), "`rocm examine --json` failed");