dstackup: drop digest.sev.txt image pin

kvinwang · kvinwang · commit 8551c9ae5e79 · 2026-07-08T18:13:26.000-07:00
diff --git a/README.md b/README.md
@@ -67,7 +67,7 @@ services:
       - "8000:8000"
 ```
 
-Deploy to a self-hosted TDX machine with the `dstackup install` -> `dstack deploy` workflow, or use [Phala Cloud](https://cloud.phala.network) for managed infrastructure. AMD SEV-SNP hosts use the same workflow when the selected guest image includes `digest.sev.txt`.
+Deploy to a self-hosted TDX machine with the `dstackup install` -> `dstack deploy` workflow, or use [Phala Cloud](https://cloud.phala.network) for managed infrastructure. AMD SEV-SNP hosts use the same workflow when the selected guest image includes the unified `digest.txt` and SNP measurement material (`measurement.snp.cbor`).
 
 Setting up dstack on your own hardware? Start with the [self-hosted quick onboarding guide](./docs/onboarding.md)
 
diff --git a/crates/dstackup/src/cli.rs b/crates/dstackup/src/cli.rs
@@ -223,8 +223,9 @@ pub(crate) struct InstallOpts {
     #[arg(long)]
     pub(crate) no_kms: bool,
 
-    /// proceed even if the app OS image can't be pinned (missing platform
-    /// digest) — apps will boot any unmeasured image and still get keys. not
+    /// proceed even if the app OS image can't be pinned in the host allowlist
+    /// (for example, a missing digest on platforms that can still boot without
+    /// it) — apps may boot an unmeasured image and still get keys. not
     /// recommended.
     #[arg(long)]
     pub(crate) allow_unpinned_image: bool,
diff --git a/crates/dstackup/src/image.rs b/crates/dstackup/src/image.rs
@@ -6,11 +6,12 @@
 //!
 //! Images are published as release tarballs at `Dstack-TEE/meta-dstack`. There
 //! are two variants — cpu (`dstack-<ver>`) and gpu (`dstack-nvidia-<ver>`).
-//! `install` validates the selected image against the platform-specific digest
-//! it needs before starting the host stack: TDX uses `digest.txt`, and
-//! SEV-SNP uses `digest.sev.txt`. HTTP + checksum are native (reqwest is
-//! already linked via the prpc client; sha2 verifies inline); only `tar` is
-//! shelled out, since GNU tar is ubiquitous and battle-tested on archive edges.
+//! `install` validates the selected image against the platform-specific files
+//! it needs before starting the host stack: all platforms use `digest.txt` as
+//! the unified OS image hash, and SEV-SNP additionally needs
+//! `measurement.snp.cbor`. HTTP + checksum are native (reqwest is already
+//! linked via the prpc client; sha2 verifies inline); only `tar` is shelled out,
+//! since GNU tar is ubiquitous and battle-tested on archive edges.
 
 use crate::cli::ImageCmd;
 use crate::systemd::tool;
@@ -364,7 +365,7 @@ pub(crate) async fn resolve_or_pull_image(
     image_dir: &str,
     requested: Option<&str>,
     require: bool,
-    required_digest: Option<&str>,
+    required_files: &[&str],
 ) -> Result<Option<String>> {
     if let Some(name) = requested {
         if !valid_image_name(name) {
@@ -375,23 +376,29 @@ pub(crate) async fn resolve_or_pull_image(
             .join("metadata.json")
             .exists()
         {
+            ensure_image_has_required_files(image_dir, name, required_files)?;
             return Ok(Some(name.to_string()));
         }
         if let Some(spec) = pull_spec(name) {
             println!("  [..] image {name} not found locally; downloading it");
             let pulled = pull(Some(&spec.version), spec.gpu, image_dir, false, false).await?;
+            ensure_image_has_required_files(image_dir, &pulled, required_files)?;
             return Ok(Some(pulled));
         }
-        return resolve_image(image_dir, Some(name), require);
+        let resolved = resolve_image(image_dir, Some(name), require)?;
+        if let Some(resolved) = &resolved {
+            ensure_image_has_required_files(image_dir, resolved, required_files)?;
+        }
+        return Ok(resolved);
     }
 
     let mut imgs = installed_images(image_dir);
-    let skipped = retain_images_with_digest(&mut imgs, image_dir, required_digest);
+    let skipped = retain_images_with_required_files(&mut imgs, image_dir, required_files);
     if let Some(newest) = imgs.pop() {
         if !skipped.is_empty() {
             println!(
                 "  [!]  ignoring image(s) without {}: {}",
-                required_digest.unwrap_or("required digest"),
+                required_files_label(required_files),
                 skipped.join(", ")
             );
         }
@@ -407,12 +414,16 @@ pub(crate) async fn resolve_or_pull_image(
     }
 
     if !require {
-        if let Some(digest) = required_digest {
+        if !required_files.is_empty() {
             if skipped.is_empty() {
-                println!("  [!]  no guest image in {image_dir} with {digest} - `dstack deploy -c <compose>` will need one (`dstackup image pull`)");
+                println!(
+                    "  [!]  no guest image in {image_dir} with {} - `dstack deploy -c <compose>` will need one (`dstackup image pull`)",
+                    required_files_label(required_files)
+                );
             } else {
                 println!(
-                    "  [!]  no guest image in {image_dir} with {digest}; ignored {} - `dstack deploy -c <compose>` will need one (`dstackup image pull`)",
+                    "  [!]  no guest image in {image_dir} with {}; ignored {} - `dstack deploy -c <compose>` will need one (`dstackup image pull`)",
+                    required_files_label(required_files),
                     skipped.join(", ")
                 );
             }
@@ -422,14 +433,16 @@ pub(crate) async fn resolve_or_pull_image(
         return Ok(None);
     }
 
-    if let Some(digest) = required_digest {
+    if !required_files.is_empty() {
         if skipped.is_empty() {
             println!(
-                "  [..] no local guest image with {digest} found; downloading the latest cpu image"
+                "  [..] no local guest image with {} found; downloading the latest cpu image",
+                required_files_label(required_files)
             );
         } else {
             println!(
-                "  [..] no local guest image with {digest} found (ignored {}); downloading the latest cpu image",
+                "  [..] no local guest image with {} found (ignored {}); downloading the latest cpu image",
+                required_files_label(required_files),
                 skipped.join(", ")
             );
         }
@@ -443,34 +456,69 @@ pub(crate) async fn resolve_or_pull_image(
         .join("metadata.json")
         .exists()
     {
+        ensure_image_has_required_files(image_dir, &pulled, required_files)?;
         Ok(Some(pulled))
     } else {
         bail!("downloaded image {pulled}, but it is not available in {image_dir}")
     }
 }
 
-fn retain_images_with_digest(
+fn retain_images_with_required_files(
     imgs: &mut Vec<String>,
     image_dir: &str,
-    required_digest: Option<&str>,
+    required_files: &[&str],
 ) -> Vec<String> {
-    let Some(required_digest) = required_digest else {
+    if required_files.is_empty() {
         return Vec::new();
-    };
+    }
     let mut skipped = Vec::new();
     imgs.retain(|name| {
-        let has_digest = Path::new(image_dir)
-            .join(name)
-            .join(required_digest)
-            .is_file();
-        if !has_digest {
+        let has_required_files = image_has_required_files(image_dir, name, required_files);
+        if !has_required_files {
             skipped.push(name.clone());
         }
-        has_digest
+        has_required_files
     });
     skipped
 }
 
+fn image_has_required_files(image_dir: &str, image: &str, required_files: &[&str]) -> bool {
+    required_files
+        .iter()
+        .all(|file| Path::new(image_dir).join(image).join(file).is_file())
+}
+
+fn ensure_image_has_required_files(
+    image_dir: &str,
+    image: &str,
+    required_files: &[&str],
+) -> Result<()> {
+    let missing = missing_required_files(image_dir, image, required_files);
+    if missing.is_empty() {
+        return Ok(());
+    }
+    bail!(
+        "image {image:?} under {image_dir} is missing required file(s): {}",
+        missing.join(", ")
+    )
+}
+
+fn missing_required_files(image_dir: &str, image: &str, required_files: &[&str]) -> Vec<String> {
+    required_files
+        .iter()
+        .filter(|file| !Path::new(image_dir).join(image).join(file).is_file())
+        .map(|file| (*file).to_string())
+        .collect()
+}
+
+fn required_files_label(required_files: &[&str]) -> String {
+    if required_files.is_empty() {
+        "required file(s)".to_string()
+    } else {
+        required_files.join(", ")
+    }
+}
+
 fn pull_spec(name: &str) -> Option<PullSpec> {
     if !valid_image_name(name) {
         return None;
diff --git a/crates/dstackup/src/install.rs b/crates/dstackup/src/install.rs
@@ -93,13 +93,12 @@ pub(crate) async fn cmd_install(mut o: InstallOpts) -> Result<()> {
     //    empty, download the latest CPU image through the verified image path.
     //    Pinning is validated before installing managed binaries, so an
     //    incompatible image fails without leaving a half-built host install.
-    let required_digest =
-        (!o.no_kms && !o.allow_unpinned_image).then_some(os_image_digest_file(platform));
+    let required_image_files = required_image_files(platform, !o.no_kms && !o.allow_unpinned_image);
     o.image = crate::image::resolve_or_pull_image(
         &images,
         o.image.as_deref(),
         !o.no_kms,
-        required_digest,
+        required_image_files,
     )
     .await?;
     let os_image_hash = resolve_image_pin(&o, &images, platform)?;
@@ -151,8 +150,10 @@ pub(crate) async fn cmd_install(mut o: InstallOpts) -> Result<()> {
     // The KMS's own image download-verify stays off for the single-node flow
     // (it would need a published image source), but we PIN the app OS image in
     // the webhook allowlist (resolved in preflight, fail-closed): digest.txt
-    // holds the measured image hash the KMS reports for an app, so an app cannot
-    // boot under a different, unmeasured image and still receive keys.
+    // holds the unified measured image hash the KMS reports for an app (with
+    // platform measurement material such as measurement.snp.cbor committed by
+    // sha256sum.txt), so an app cannot boot under a different, unmeasured image
+    // and still receive keys.
     // bootAuth/kms ignores osImages, so the KMS bootstrap itself is unaffected.
     let host_cfg = HostConfig {
         auth_webhook_url: format!("http://10.0.2.2:{}", o.auth_port),
@@ -832,15 +833,20 @@ fn split_addr_port(ep: &str) -> Result<(String, u16)> {
     ))
 }
 
-fn os_image_digest_file(platform: Platform) -> &'static str {
+fn os_image_digest_file(_platform: Platform) -> &'static str {
+    "digest.txt"
+}
+
+fn required_image_files(platform: Platform, require_pin: bool) -> &'static [&'static str] {
     match platform {
-        Platform::AmdSevSnp => "digest.sev.txt",
-        Platform::Tdx => "digest.txt",
+        Platform::AmdSevSnp => &["digest.txt", "measurement.snp.cbor"],
+        Platform::Tdx if require_pin => &["digest.txt"],
+        Platform::Tdx => &[],
     }
 }
 
-/// read the measured OS-image hash from the guest image's platform-specific
-/// digest file, used to pin which image apps may boot.
+/// read the measured OS-image hash from the guest image's unified digest file,
+/// used to pin which image apps may boot.
 /// Returns None when there's no image selected or no readable digest.
 fn resolve_os_image_hash(images: &str, image: Option<&str>, platform: Platform) -> Option<String> {
     let img = image?;
@@ -851,7 +857,7 @@ fn resolve_os_image_hash(images: &str, image: Option<&str>, platform: Platform)
 }
 
 /// resolve the OS-image pin, failing CLOSED: in KMS mode a missing/empty
-/// platform digest is a hard error (an unpinned app could boot any unmeasured
+/// image digest is a hard error (an unpinned app could boot any unmeasured
 /// image and still get keys), unless the operator opts out with
 /// `--allow-unpinned-image`. Returns Some(hash) to pin, or None when pinning
 /// is deliberately off (`--no-kms`, or the explicit opt-out).
diff --git a/docs/hardware-enablement.md b/docs/hardware-enablement.md
@@ -49,7 +49,7 @@ cat /sys/module/kvm_amd/parameters/sev_snp
 
 The AMDSEV verification path expects `dmesg` to show SEV-SNP and RMP initialization, and `sev_snp` to read `Y`.
 
-Host enablement is necessary but not sufficient for onboarding with KMS. The selected guest image must also contain `digest.sev.txt`, which `dstackup install` uses to pin apps to the measured SNP OS image.
+Host enablement is necessary but not sufficient for onboarding with KMS. The selected guest image must also contain the unified `digest.txt` plus `measurement.snp.cbor`; `dstackup install` uses them to pin apps to the measured SNP OS image and ensure the SNP launch material is available.
 
 ## What dstackup checks
 
diff --git a/docs/onboarding.md b/docs/onboarding.md
@@ -12,7 +12,7 @@ sudo dstack deploy \
 curl http://127.0.0.1:8080/
 ```
 
-AMD SEV-SNP hosts use the same `dstackup` and `dstack` commands after you provide a guest image that contains the SNP image digest (`digest.sev.txt`). As of June 28, 2026, the latest stable CPU image from `meta-dstack` is TDX-pinned only, so the copy-paste path below is not the AMD happy path yet.
+AMD SEV-SNP hosts use the same `dstackup` and `dstack` commands after you provide a guest image that contains the unified image digest (`digest.txt`) and SNP measurement material (`measurement.snp.cbor`). If your image predates SNP measurement material, provide a newer or custom SNP-capable image before running `dstackup install`.
 
 For multi-node production, Gateway TLS, custom domains, or on-chain governance, use the full [deployment guide](./deployment.md).
 
@@ -93,7 +93,7 @@ sudo dstackup install --key-provider-src /path/to/key-provider-build
 sudo dstackup install --use-existing-key-provider 127.0.0.1:3443
 ```
 
-On AMD SEV-SNP, no SGX key provider is needed. The selected guest image must include `digest.sev.txt`; otherwise, `dstackup install` fails before it starts the host units because apps could not be pinned to the measured SNP OS image.
+On AMD SEV-SNP, no SGX key provider is needed. The selected guest image must include `digest.txt` and `measurement.snp.cbor`; otherwise, `dstackup install` fails before it starts the host units because apps could not be pinned to the measured SNP OS image or launched with the required SNP measurement material.
 
 To use a GPU image, pull it before install:
 
@@ -236,7 +236,7 @@ sudo /opt/dstack-test/bin/dstackup destroy --prefix /opt/dstack-test --purge
 This onboarding path is designed for one operator on one host.
 
 - The VMM dashboard and management API bind to `127.0.0.1` by default. Use SSH tunneling for remote access.
-- `dstackup install` pins the app OS image hash from the selected guest image (`digest.txt` for TDX, `digest.sev.txt` for SEV-SNP). If the digest cannot be read, install fails unless you pass `--allow-unpinned-image`.
+- `dstackup install` pins the app OS image hash from the selected guest image (`digest.txt` on all platforms; SEV-SNP images must also carry `measurement.snp.cbor`). If pinning is enabled and the digest cannot be read, install fails; SEV-SNP also fails when the SNP measurement material is missing.
 - `dstack deploy` registers the app compose hash in the local auth allowlist from `dstackup install`. Without that allowlist update, a KMS-mode app can boot but will not receive keys.
 - Gateway is not part of this flow. Apps are exposed through direct host port mappings.
 
@@ -256,15 +256,15 @@ If a release does not publish a SHA-256 digest, `dstackup image pull` and `dstac
 
 If you use a custom prefix or image directory, pass the same `--prefix` or `--image-path` to `install` and `image` commands.
 
-### Missing `digest.sev.txt` on AMD SEV-SNP
+### Missing SNP image material on AMD SEV-SNP
 
-TDX images pin apps with `digest.txt`. AMD SEV-SNP images pin apps with `digest.sev.txt`. If the selected image does not contain `digest.sev.txt`, install fails with:
+All platforms pin apps with the unified `digest.txt`. AMD SEV-SNP images must also contain `measurement.snp.cbor`, which binds the SNP launch measurement material committed by `sha256sum.txt`. If the selected image does not contain the required files, install fails with an error such as:
 
 ```text
-no os-image pin: could not read digest.sev.txt
+image "dstack-..." under /var/lib/dstack/images is missing required file(s): measurement.snp.cbor
 ```
 
-Use `--image` or `--image-path` with an SNP-capable image that contains `digest.sev.txt`. Do not use `--allow-unpinned-image` for onboarding unless you intentionally want apps to boot without OS-image pinning.
+Use `--image` or `--image-path` with an SNP-capable image that contains `digest.txt` and `measurement.snp.cbor`. `--allow-unpinned-image` only bypasses host allowlist pinning; it does not make a TDX-only image SNP-capable.
 
 ### No key provider on TDX
 
