Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
18 changes: 12 additions & 6 deletions Guide/src/dev_guide/snapshot_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -25,11 +25,15 @@ crate's protobuf encoding.

Every snapshot uses manifest version 2 with format magic
`OPENVMM_SNAPSHOT_V2\0`. Restore rejects any other version or magic with
`E_SNAPSHOT_VERSION`, which asks for a recapture. A microVM snapshot's machine
contract carries the NVX time ABI records (the time contract and the CPU
profile record), and a host-driven standard-machine snapshot has no machine
contract. Tiered microVM snapshots record capture tier, clone/resume policy,
and consumed configuration sections.
`E_SNAPSHOT_VERSION`, which asks for a recapture. It decodes the version,
field 1, and then the magic, field 10, each alone before the rest of the
manifest, since earlier formats give some fields other types: version 6, the
manifest of earlier releases, keeps its machine contract in field 11, and the
first version 2, which has no magic, keeps artifact digests in fields 9 and 10.
A microVM snapshot's machine contract carries the NVX time ABI records (the
time contract and the CPU profile record), and a host-driven standard-machine
snapshot has no machine contract. Tiered microVM snapshots record capture
tier, clone/resume policy, and consumed configuration sections.

The format is a local machine-state contract, not an authenticated container.
Every snapshot receives the same regular-file, no-follow/no-reparse, bounded
Expand Down Expand Up @@ -209,7 +213,9 @@ Key unsupported categories:
## Extending the format

When adding new fields to `SnapshotManifest`, use the next available mesh
tag number.
tag number other than 18, 19, and 20: upstream OpenVMM assigns field 18 to
the `snapshot_id` that its SaveVM API records, and reserves fields 19 and 20
for `compatibility_bundle_digest` and `memory_artifacts`.
The protobuf encoding is forward-compatible: older readers will
ignore unknown fields. However, removing or reordering existing fields is a
breaking change. See [Save State](contrib/save-state.md) for the full set of
Expand Down
4 changes: 4 additions & 0 deletions openvmm/openvmm_helpers/src/snapshot.rs
Original file line number Diff line number Diff line change
Expand Up @@ -70,6 +70,10 @@ pub struct SnapshotManifest {
/// Bitmask of configuration sections consumed before capture.
#[mesh(15)]
pub consumed_config_sections: u32,
// Upstream OpenVMM assigns field 18 to the `snapshot_id` that its SaveVM
// API records, and reserves fields 19 and 20 for
// `compatibility_bundle_digest` and `memory_artifacts`, so no other field
// of this manifest takes them.
}

/// Validate that a snapshot manifest is compatible with the running VM config.
Expand Down
69 changes: 62 additions & 7 deletions openvmm/openvmm_helpers/src/snapshot/format.rs
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,8 @@
use super::MANIFEST_VERSION;
use super::SnapshotManifest;
use super::microvm;
use anyhow::Context;
use mesh::payload::Protobuf;
use mesh::payload::Timestamp;
use sha2::Digest;
use virt::time_abi::TimeAbiCode;
Expand Down Expand Up @@ -101,27 +103,80 @@ pub(super) fn verify_digest(
Ok(())
}

/// Validates the manifest's format identity: [`MANIFEST_VERSION`], the
/// matching magic, and the saved-state schema. Any other version or magic is
/// The version of a manifest, which every manifest format, upstream's
/// included, keeps in field 1.
#[derive(Protobuf)]
#[mesh(package = "openvmm.snapshot")]
struct ManifestVersion {
#[mesh(1)]
version: u32,
}

/// The format magic of a manifest of [`MANIFEST_VERSION`], which it keeps in
/// field 10.
#[derive(Protobuf)]
#[mesh(package = "openvmm.snapshot")]
struct ManifestFormatMagic {
#[mesh(10)]
format_magic: Vec<u8>,
}

/// Decodes a manifest of this format, one that [`validate_manifest_header`]
/// accepts.
///
/// Earlier formats give some field numbers other types, so decoding one of
/// their manifests whole fails as if it were malformed. This decodes the
/// version alone, which every format keeps in field 1, then the magic alone,
/// and refuses any other version or magic with `E_SNAPSHOT_VERSION` before it
/// decodes the rest. The magic comes second, since only the formats of this
/// version agree on the type of field 10.
pub(super) fn decode_manifest(bytes: &[u8]) -> anyhow::Result<SnapshotManifest> {
let ManifestVersion { version } =
mesh::payload::decode(bytes).context("failed to decode snapshot manifest")?;
validate_manifest_version(version)?;
let ManifestFormatMagic { format_magic } =
mesh::payload::decode(bytes).context("failed to decode snapshot manifest")?;
validate_format_magic(&format_magic)?;
let manifest: SnapshotManifest =
mesh::payload::decode(bytes).context("failed to decode snapshot manifest")?;
validate_manifest_header(&manifest)?;
Ok(manifest)
}

/// Refuses any other manifest version than [`MANIFEST_VERSION`] with
/// `E_SNAPSHOT_VERSION`, which asks for a recapture.
pub(super) fn validate_manifest_header(manifest: &SnapshotManifest) -> anyhow::Result<()> {
if manifest.version != MANIFEST_VERSION {
fn validate_manifest_version(version: u32) -> anyhow::Result<()> {
if version != MANIFEST_VERSION {
return Err(TimeAbiError::new(
TimeAbiCode::SnapshotVersion,
format!(
"snapshot manifest version {} is not supported (expected {MANIFEST_VERSION}); recapture the snapshot",
manifest.version
"snapshot manifest version {version} is not supported (expected {MANIFEST_VERSION}); recapture the snapshot"
),
)
.into());
}
if manifest.format_magic != SNAPSHOT_FORMAT_MAGIC {
Ok(())
}

/// Refuses any other format magic than [`SNAPSHOT_FORMAT_MAGIC`] with
/// `E_SNAPSHOT_VERSION`, which asks for a recapture.
fn validate_format_magic(format_magic: &[u8]) -> anyhow::Result<()> {
if format_magic != SNAPSHOT_FORMAT_MAGIC {
return Err(TimeAbiError::new(
TimeAbiCode::SnapshotVersion,
"snapshot format magic is invalid; recapture the snapshot",
)
.into());
}
Ok(())
}

/// Validates the manifest's format identity: [`MANIFEST_VERSION`], the
/// matching magic, and the saved-state schema. Any other version or magic is
/// `E_SNAPSHOT_VERSION`, which asks for a recapture.
pub(super) fn validate_manifest_header(manifest: &SnapshotManifest) -> anyhow::Result<()> {
validate_manifest_version(manifest.version)?;
validate_format_magic(&manifest.format_magic)?;
anyhow::ensure!(
manifest.saved_state_schema_version == SAVED_STATE_SCHEMA_VERSION,
"snapshot saved-state schema version {} is unsupported",
Expand Down
153 changes: 150 additions & 3 deletions openvmm/openvmm_helpers/src/snapshot/restore.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@ use super::format::RESUME_CLAIM_FILE_NAME;
use super::format::SCRATCH_FILE_NAME;
use super::format::SNAPSHOT_RESTORE_POLICY_RESUME;
use super::format::STATE_FILE_NAME;
use super::format::decode_manifest;
use super::format::validate_manifest_contents;
use super::format::validate_manifest_header;
use super::fs::OpenedFileGeneration;
Expand Down Expand Up @@ -193,9 +194,7 @@ fn read_snapshot_manifest_from_directory(
fn decode_snapshot_manifest(manifest_file: &std::fs::File) -> anyhow::Result<SnapshotManifest> {
let manifest_bytes =
read_bounded_open_file(manifest_file, MAX_MANIFEST_SIZE_BYTES, "snapshot manifest")?;
let manifest: SnapshotManifest =
mesh::payload::decode(&manifest_bytes).context("failed to decode snapshot manifest")?;
validate_manifest_header(&manifest)?;
let manifest = decode_manifest(&manifest_bytes)?;
validate_manifest_contents(&manifest)?;
if let Some(contract) = &manifest.machine_contract {
microvm::validate_machine_contract_shape(
Expand Down Expand Up @@ -413,8 +412,11 @@ mod tests {
use super::super::publish::write_snapshot_from_owned_memory_and_scratch_files;
use super::super::tests::test_manifest;
use super::*;
use mesh::payload::Protobuf;
use mesh::payload::Timestamp;
use openvmm_defs::microvm::MICROVM_COMMAND_LINE_MAX_SIZE;
use openvmm_defs::microvm::check_microvm_command_line;
use sha2::Digest;
use std::io::Read;
#[cfg(any(target_os = "linux", windows))]
use std::io::Seek;
Expand Down Expand Up @@ -612,6 +614,151 @@ mod tests {
assert!(error.contains("recapture the snapshot"), "{error}");
}

/// Returns the errors of reading a snapshot whole and its manifest alone,
/// once `manifest` replaces the manifest of a snapshot of this format.
fn read_errors_with_manifest(manifest: &[u8]) -> Vec<String> {
let dir = tempfile::tempdir().unwrap();
let snap_dir = dir.path().join("snap");
let mem_path = dir.path().join("memory.bin");
std::fs::write(&mem_path, vec![0_u8; 1024]).unwrap();
write_snapshot(&snap_dir, &test_manifest(), b"state", &mem_path).unwrap();
std::fs::write(snap_dir.join(MANIFEST_FILE_NAME), manifest).unwrap();
[
read_snapshot(&snap_dir, 1024).err().unwrap(),
read_snapshot_manifest(&snap_dir).err().unwrap(),
]
.iter()
.map(|error| format!("{error:#}"))
.collect()
}

#[test]
fn read_snapshot_refuses_a_version_6_manifest_by_its_version() {
// The manifest of earlier OpenVMM releases, version 6, gives fields 11
// and 13 other types than this format does: its machine contract, a
// message, is where this format keeps the saved-state schema version,
// a varint, and its schema version where this format keeps the capture
// tier, a string.
#[derive(Protobuf)]
#[mesh(package = "openvmm.snapshot")]
struct ManifestV6 {
#[mesh(1)]
version: u32,
#[mesh(2)]
created_at: Timestamp,
#[mesh(3)]
openvmm_version: String,
#[mesh(4)]
memory_size_bytes: u64,
#[mesh(5)]
vp_count: u32,
#[mesh(6)]
page_size: u32,
#[mesh(7)]
architecture: String,
#[mesh(8)]
state_size_bytes: u64,
#[mesh(11)]
machine_contract: Option<microvm::SnapshotMachineContract>,
#[mesh(12)]
format_magic: Vec<u8>,
#[mesh(13)]
saved_state_schema_version: u32,
#[mesh(14)]
saved_state_root_type: String,
#[mesh(15)]
snapshot_tier: String,
#[mesh(16)]
restore_policy: String,
#[mesh(17)]
consumed_config_sections: u32,
}

let manifest = mesh::payload::encode(ManifestV6 {
version: 6,
created_at: Timestamp {
seconds: 1234567890,
nanos: 0,
},
openvmm_version: "test-0.1.0".to_owned(),
memory_size_bytes: 1024,
vp_count: 2,
page_size: 4096,
architecture: "x86_64".to_owned(),
state_size_bytes: 5,
machine_contract: Some(test_machine_contract()),
format_magic: b"OPENVMM_SNAPSHOT_V6\0".to_vec(),
saved_state_schema_version: 1,
saved_state_root_type: "openvmm.SavedState".to_owned(),
snapshot_tier: "platform".to_owned(),
restore_policy: "clone".to_owned(),
consumed_config_sections: 1,
});
for error in read_errors_with_manifest(&manifest) {
assert!(error.contains("[E_SNAPSHOT_VERSION]"), "{error}");
assert!(
error.contains("snapshot manifest version 6 is not supported"),
"{error}"
);
assert!(error.contains("recapture the snapshot"), "{error}");
}
}

#[test]
fn read_snapshot_refuses_an_early_version_2_manifest_by_its_magic() {
// The first manifest version 2, which predates the format magic, kept
// the SHA-256 digests of `state.bin` and `memory.bin` in fields 9 and
// 10, where this format keeps its machine contract and its magic.
#[derive(Protobuf)]
#[mesh(package = "openvmm.snapshot")]
struct ManifestV2WithDigests {
#[mesh(1)]
version: u32,
#[mesh(2)]
created_at: Timestamp,
#[mesh(3)]
openvmm_version: String,
#[mesh(4)]
memory_size_bytes: u64,
#[mesh(5)]
vp_count: u32,
#[mesh(6)]
page_size: u32,
#[mesh(7)]
architecture: String,
#[mesh(8)]
state_size_bytes: u64,
#[mesh(9)]
state_sha256: Vec<u8>,
#[mesh(10)]
memory_sha256: Vec<u8>,
}

let manifest = mesh::payload::encode(ManifestV2WithDigests {
version: 2,
created_at: Timestamp {
seconds: 1234567890,
nanos: 0,
},
openvmm_version: "test-0.1.0".to_owned(),
memory_size_bytes: 1024,
vp_count: 2,
page_size: 4096,
architecture: "x86_64".to_owned(),
state_size_bytes: 5,
state_sha256: sha2::Sha256::digest(b"state").to_vec(),
memory_sha256: sha2::Sha256::digest([0_u8; 1024]).to_vec(),
});
for error in read_errors_with_manifest(&manifest) {
assert!(error.contains("[E_SNAPSHOT_VERSION]"), "{error}");
assert!(
error.contains("snapshot format magic is invalid"),
"{error}"
);
assert!(error.contains("recapture the snapshot"), "{error}");
}
}

#[test]
fn read_snapshot_rejects_a_command_line_over_the_limit_without_rewriting_it() {
let dir = tempfile::tempdir().unwrap();
Expand Down
Loading