Skip to content
4 changes: 2 additions & 2 deletions apps/rocm/src/driver_plan.rs
Original file line number Diff line number Diff line change
Expand Up @@ -1156,7 +1156,7 @@ pub(crate) mod tests {
#[cfg(unix)]
use std::process::Command as ProcessCommand;

use super::rocdxg::scoped_rocdxg_env;
use super::rocdxg::{ROCDXG_STAGING_DIR, scoped_rocdxg_env};
use super::*;
use crate::tests::ScopedTestEnv;

Expand Down Expand Up @@ -3061,7 +3061,7 @@ VERSION_ID="41"
// assertions below hold against a plan that installs nothing at all.
// Only a real install plan carries this command.
assert!(
rendered.contains("apt-get install -y '/tmp/"),
rendered.contains(&format!("apt-get install -y '{ROCDXG_STAGING_DIR}/")),
"expected a real install plan, got:\n{rendered}"
);
assert!(rendered.contains("post_install_checks:"));
Expand Down
622 changes: 596 additions & 26 deletions apps/rocm/src/driver_plan/rocdxg.rs

Large diffs are not rendered by default.

19 changes: 15 additions & 4 deletions crates/rocm-core/src/diagnose/wsl.rs
Original file line number Diff line number Diff line change
Expand Up @@ -176,7 +176,7 @@ pub(super) fn check_wsl_3_rocdxg_missing(e: &Examination, symptom: &str) -> Diag
fix_id: "fix-wsl-3-rocdxg-missing".to_owned(),
verify: "ldconfig -p | grep librocdxg".to_owned(),
notes: vec![
"This downloads and installs a .deb with sudo, so `rocm fix` prints it rather than running it. `rocm install driver` shows the full plan, and checks the download against a digest pinned for that ROCDXG release.".to_owned(),
"This downloads and installs a .deb with sudo, so `rocm fix` prints it rather than running it. `rocm install driver` shows the full plan, and checks the package against a digest pinned for that ROCDXG release after root has placed it where only root can write, so the file checked is the file installed.".to_owned(),
],
..Fix::default()
};
Expand Down Expand Up @@ -531,10 +531,21 @@ mod tests {
// Verification is no longer something the user has to remember to turn
// on: `rocm install driver` pins a digest per release. The note has to
// say so, because a print-only recipe is all the user sees here.
//
// This pins the wording only. That the plan really checks the copy
// root installs, from a directory only root can write, is proved by
// `wsl_rocdxg_generated_steps_install_exactly_the_verified_file` in
// `apps/rocm/src/driver_plan/rocdxg.rs`, which executes the generated
// steps.
let note = fix
.notes
.iter()
.find(|n| n.contains("digest"))
.unwrap_or_else(|| panic!("must state that the package is verified: {:?}", fix.notes));
assert!(
fix.notes.iter().any(|n| n.contains("digest")),
"must state that the download is verified: {:?}",
fix.notes
note.contains("only root can write")
&& note.contains("the file checked is the file installed"),
"must state that the checked file is the root-placed copy that is installed: {note}"
);
assert!(
fix.commands
Expand Down
18 changes: 17 additions & 1 deletion crates/rocm-core/src/fix/catalog.rs
Original file line number Diff line number Diff line change
Expand Up @@ -714,7 +714,7 @@ pub(super) const RECIPES: &[FixRecipe] = &[
verify_linux: None,
notes: &[
"Print-only on purpose: this downloads a .deb from a release page and installs it with sudo. `rocm install driver` prints the plan first so the URL and the package are reviewable before anything runs.",
"The download is checked against a digest pinned for that ROCDXG release. To install a release rocm-cli has no digest for, set ROCM_CLI_ROCDXG_SHA256 to the one published with it.",
"The package is checked against a digest pinned for that ROCDXG release, on the copy root installs from a directory only root can write. To install a release rocm-cli has no digest for, set ROCM_CLI_ROCDXG_SHA256 to the one published with it.",
],
doc_url: None,
applies_on: PRINT_ON_WSL,
Expand Down Expand Up @@ -1449,6 +1449,22 @@ mod tests {
.collect()
}

#[test]
fn rocdxg_missing_note_says_the_checked_copy_is_the_installed_one() {
// Pins the wording only. That the plan really checks the copy root
// installs, from a directory only root can write, is proved by
// `wsl_rocdxg_generated_steps_install_exactly_the_verified_file` in
// `apps/rocm/src/driver_plan/rocdxg.rs`, which executes the generated
// steps.
let recipe = find_recipe("fix-wsl-3-rocdxg-missing").expect("recipe exists");
assert!(
recipe.notes.iter().any(|n| n.contains("digest")
&& n.contains("on the copy root installs from a directory only root can write")),
"{:?}",
recipe.notes
);
}

// Ubuntu 26.04 gets the DKMS driver plan (`dkms_driver_plan_is_supported`),
// so no recipe may still describe it as in-tree or unplanned.
#[test]
Expand Down
2 changes: 1 addition & 1 deletion docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ The `rocm` binary: the clap command tree, a handler module for most commands, an
| [`diagnose_model.rs`](../apps/rocm/src/diagnose_model.rs) | The binary's side of `rocm diagnose --model`'s GGUF context estimate: the `--kv-cache-type` and model flags, the `--report` note, and the device-visibility-mask caveat. | domain |
| [`driver_install.rs`](../apps/rocm/src/driver_install.rs) | `rocm install driver` (`install_driver`, `reconcile_driver_install`): runs an approved plan's commands and persists the driver install state. It re-exports `host_install_driver_only_reports` from [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) for its callers, [`tool_policy.rs`](../apps/rocm/src/tool_policy.rs) and [`freeform_planner.rs`](../apps/rocm/src/freeform_planner.rs). | relocation |
| [`driver_plan.rs`](../apps/rocm/src/driver_plan.rs) | The `rocm install driver` plan: its model, its printed text, and the per-distro builders (apt, dnf, zypper) from the host's examination and os-release. | domain |
| [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) | The WSL2 rocDXG driver plan, which installs the digest-pinned `rocdxg-roct` package or refuses when the download cannot be authenticated. | domain |
| [`driver_plan/rocdxg.rs`](../apps/rocm/src/driver_plan/rocdxg.rs) | The WSL2 rocDXG driver plan, which stages the digest-pinned `rocdxg-roct` package in a root-only directory, checks and installs that same file, or refuses when the download cannot be authenticated. | domain |
| [`endpoint_keys.rs`](../apps/rocm/src/endpoint_keys.rs) | Per-service inference-endpoint API keys, stored in owner-only files under the services directory, keyed by service id. | relocation |
| [`engine_install_env.rs`](../apps/rocm/src/engine_install_env.rs) | Which runtime an engine installs into and where its environment lives (`engine_manages_own_runtime`, `env_root_for_engine_install`), shared by the engine and SDK install paths. | relocation |
| [`engine_ipc.rs`](../apps/rocm/src/engine_ipc.rs) | Locating an engine's plugin binary, the engine request entry points (answering from the in-process built-in handler, or running the resolved engine binary with `stdio`), and the in-process built-in engine path. `engine_stdio_child_request` hands the child to the stdio client `rocm` shares with `rocmd`, [`stdio_client.rs`](../crates/rocm-engine-protocol/src/stdio_client.rs), and chooses what `rocm` asks of it: the app paths and engine environments root for the child, progress for an install, and the child's stderr forwarded to the terminal. | relocation |
Expand Down
8 changes: 6 additions & 2 deletions docs/release-trust.md
Original file line number Diff line number Diff line change
Expand Up @@ -179,8 +179,12 @@ All of those checks happen before activation. Run the current host's set with
The ROCDXG `.deb` is fetched over plain HTTPS from a release page and handed to
`apt-get install`, which runs its maintainer scripts as root. rocm-cli therefore
carries a SHA-256 digest for each published ROCDXG release and checks the
download against it before the install step; on a mismatch the plan stops before
anything runs as root. Verification is on by default and needs nothing set.
package against it before the install step; on a mismatch the plan stops before
the package's maintainer scripts run. The check is made on a copy root has
placed in `/var/cache/rocm-cli/rocdxg/`, which only root can write, and that
same file is what `apt-get install` reads, so no other local user can change
the package between the check and the install. Verification is on by default
and needs nothing set.

`ROCM_CLI_ROCDXG_SHA256` supplies a digest for a release rocm-cli has none for,
and overrides the pinned digest for one it does:
Expand Down
26 changes: 26 additions & 0 deletions docs/testing.md
Original file line number Diff line number Diff line change
Expand Up @@ -3858,6 +3858,8 @@ Release trust checks:
cargo test -p rocm --bin rocm metadata_signature_verification_accepts_generated_key_and_rejects_tamper
cargo test -p rocm-core model_recipe_index_signature_accepts_generated_key_and_rejects_tamper
cargo test -p rocm --bin rocm wsl_rocdxg_generated_digest_step_accepts_only_the_matching_file
cargo test -p rocm --bin rocm wsl_rocdxg_generated_steps_install_exactly_the_verified_file
cargo test -p rocm --bin rocm wsl_doc_manual_steps_stop_before_the_check_when_the_download_fails
python scripts/release_readiness.py --self-test
bash scripts/setup-wsl-portable-build-deps.sh --self-test
bash scripts/reclaim-gpu.sh --self-test
Expand Down Expand Up @@ -3892,6 +3894,30 @@ that is then installed as root, and this replaces the self-test that shipped
with the removed `scripts/wsl_setup_rocdxg.sh`. It needs a POSIX shell and
`sha256sum`, so it is Unix-only.

`wsl_rocdxg_generated_steps_install_exactly_the_verified_file` runs every
Execute step of that plan, each in its own `sh -c` as the CLI does, against
stand-ins for `sudo`, `curl`, `install`, `apt-get` and `ldconfig`. It proves the
file `apt-get` installs is the root-staged copy the digest was checked against,
that a tampered download stops the plan before `apt-get`, and that the private
download directory and the staged copy are both removed after a successful
install. When the check or `apt-get` fails, it checks the rejected package is
left in the root-only directory and that the next run of the same version
replaces it. It also checks the staging directories end up mode 0755. The
`curl` stand-in fails if it is run under `sudo` or asked to write anywhere but
a 0700 directory directly under `$TMPDIR`, so a plan that downloads as root or
straight into the staging directory fails the test. It is Unix-only too.
`wsl_rocdxg_plan_never_installs_from_a_path_another_user_can_write` checks the
same layout on the plan text for both the `sudo` and the already-root plan, and
scenario `@id:driver-install-wsl-dry-run-plan` checks it on the `--dry-run`
output on the `@requires-wsl` lane.
`wsl_doc_manual_steps_stop_before_the_check_when_the_download_fails` runs the
manual steps from [wsl.md](wsl.md) against the same kind of stand-ins. With a
copy an earlier run left staged and a download that fails, it checks that the
block stops before the digest check, installs nothing and exits non-zero, and
that the private download directory is removed. A failed install also exits
non-zero and removes that directory, and a good download installs once and
exits zero. It is Unix-only.

The eight native Linux GPU preflights are one script,
[`gpu-preflight.sh`](../.github/scripts/gpu-preflight.sh), which each lane runs
with its own `GPU_PREFLIGHT_MIN_FREE_GIB` (16 on the discrete lanes, 8 on
Expand Down
41 changes: 32 additions & 9 deletions docs/wsl.md
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,16 @@ SHA-256 digest for each published ROCDXG release and checks the `.deb` against
it; on a mismatch the plan stops before `apt install` runs the package's
maintainer scripts as root. Nothing needs to be set for this.

The check covers the exact file root installs. The `.deb` is downloaded without
`sudo`, as whoever runs `rocm`, into a private `mktemp -d` directory, copied by
root into `/var/cache/rocm-cli/rocdxg/` (which only root can write), checked
there, then installed from there and removed. It is never staged under a fixed
name in a shared directory such as `/tmp`, where another local user could
replace it between the check and the install. A package that fails the check,
or that `apt` fails to install, is left in that root-only directory; the next
run for the same version replaces it, and `sudo rm -f
/var/cache/rocm-cli/rocdxg/*.deb` clears what an abandoned version left.

To install a release other than the pinned one, set `ROCM_CLI_ROCDXG_VERSION`.
Because ROCm CLI has no digest for a release it predates, supply one:

Expand All @@ -80,9 +90,15 @@ unverified.
### Doing it by hand

The equivalent manual steps, for reference or for a host where the CLI is not
installed yet. Do not skip the `sha256sum -c` line, because `apt install` runs
the package's maintainer scripts as root. `rocm install driver` checks the
download against a digest pinned in the ROCm CLI source
installed yet. Do not skip the `sha256sum -c` check, because `apt install`
runs the package's maintainer scripts as root, and run it on the root-owned
copy rather than on a file in `/tmp` that another user could swap after it is
checked. Each command in the chain runs only if the one before it succeeded,
so a failed download stops the block before the check rather than letting it
check and reinstall a copy an earlier run left staged. The chain runs in a
subshell whose exit removes the private download directory either way, and the
block's exit status is the chain's, so a failed download, check or install
does not report success. `rocm install driver` checks the root-owned copy against a digest pinned in the ROCm CLI source
(`ROCDXG_PINNED_DIGESTS` in `apps/rocm/src/driver_plan/rocdxg.rs`), which also
catches a replaced release asset. A digest read from the release page at
install time catches only a corrupted download. For a version listed in
Expand All @@ -94,12 +110,19 @@ ROCDXG_VERSION=<version>
ROCDXG_SHA256=<64-hex-sha256>
sudo apt-get update
sudo apt-get install -y ca-certificates curl
curl -L -o "/tmp/rocdxg-roct_${ROCDXG_VERSION}_amd64.deb" \
"https://github.com/ROCm/librocdxg/releases/download/v${ROCDXG_VERSION}/rocdxg-roct_${ROCDXG_VERSION}_amd64.deb"
printf '%s %s\n' "${ROCDXG_SHA256}" \
"/tmp/rocdxg-roct_${ROCDXG_VERSION}_amd64.deb" | sha256sum -c -
sudo apt install -y "/tmp/rocdxg-roct_${ROCDXG_VERSION}_amd64.deb"
sudo ldconfig
ROCDXG_DEB="rocdxg-roct_${ROCDXG_VERSION}_amd64.deb"
ROCDXG_STAGED="/var/cache/rocm-cli/rocdxg/${ROCDXG_DEB}"
(
d="$(mktemp -d)" && trap 'rm -rf "$d"' EXIT &&
sudo install -d -m 0755 -o root -g root /var/cache/rocm-cli /var/cache/rocm-cli/rocdxg &&
curl -L --fail -o "$d/${ROCDXG_DEB}" \
"https://github.com/ROCm/librocdxg/releases/download/v${ROCDXG_VERSION}/${ROCDXG_DEB}" &&
sudo install -m 0644 "$d/${ROCDXG_DEB}" "${ROCDXG_STAGED}" &&
printf '%s %s\n' "${ROCDXG_SHA256}" "${ROCDXG_STAGED}" | sha256sum -c - &&
sudo apt install -y "${ROCDXG_STAGED}" &&
sudo rm -f "${ROCDXG_STAGED}" &&
sudo ldconfig
)
```

Source-build alternative. Set `win_sdk` to the Windows SDK version installed on
Expand Down
Loading
Loading