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
16 changes: 12 additions & 4 deletions Guide/src/reference/devices/virtio/virtio-fs.md
Original file line number Diff line number Diff line change
Expand Up @@ -353,10 +353,18 @@ access, such as a handle open for writing on a file that a guest caller owns.
OpenVMM releases that predate `--mount-owner` reject the device state of a
`caller` attachment rather than restore it as `vmm`.

A snapshot captured without `--mount` records the slot as dormant. It may
restore without an attachment, or bind one new `--mount` attachment to the
slot, but not an aggregate. Because execution resumes after the cold-boot
mount hook, the guest must mount the newly attached backend explicitly:
A snapshot captured without `--mount` or `--mount-aggregate` records the slot
as dormant. It may restore without an attachment, or bind one new `--mount`
attachment to the slot. A platform snapshot may instead bind a new aggregate,
with `--mount-aggregate` and its `--mount-child` options, policy paths, and
`--mount-owner` mode, which OpenVMM validates as at a cold boot, before any
vCPU runs; snapshots of other tiers, and untiered snapshots, cannot. Either
attachment keeps the slot's device, whose stable ID, tag, MMIO range,
interrupt, features, and queues the snapshot fixes, and the captured kernel
command line, which has no `virtfs_*` tokens, so OpenVMM tells the guest
nothing about the new attachment. Because execution resumes after the
cold-boot mount hook, the guest must learn the attachment from its host and
mount the newly attached backend explicitly:

```bash
mkdir -p /mnt/share
Expand Down
16 changes: 11 additions & 5 deletions Guide/src/reference/openvmm/management/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -352,9 +352,14 @@ describes the source definitions.
same guest target and the same `--mount-child` options, in the same order,
with the same canonical host paths, kinds, modes, and policy paths.
A snapshot captured without a filesystem may remain dormant or bind one new
`--mount` to the slot. The resumed
guest must then explicitly run `mount -t virtiofs microvm <GUEST_TARGET>`
because its cold-boot mount hook has already completed.
`--mount` to the slot; a platform snapshot may instead bind a new
`--mount-aggregate` with its `--mount-child`, `--mount-deny`,
`--mount-allow`, `--mount-write`, and `--mount-owner` options, which
OpenVMM validates as it would at a cold boot. Either keeps the slot's device
and the captured command line, which has no `virtfs_*` token, so the resumed
guest must learn the guest target from its host and explicitly run
`mount -t virtiofs microvm <GUEST_TARGET>`, because its cold-boot mount hook
has already completed.
See [virtio-fs](../../devices/virtio/virtio-fs.md).
* `--snapshot-destination <DIR>`: Publish a microVM snapshot when the guest
writes to PMIO port `0x605`. The destination must not exist and its parent
Expand Down Expand Up @@ -447,8 +452,9 @@ describes the source definitions.
options in the same order. It must reproduce the manifest's exact canonical
host paths, guest target, and `ro`/`rw` modes while also supplying live
roots with the same saved identities. A snapshot advertising the dormant
slot may instead accept one new `--mount`; snapshots without that
capability reject additive attachment.
slot may instead accept one new `--mount`, and a platform snapshot also a
new `--mount-aggregate`; snapshots without that capability reject additive
attachment.

When the snapshot contains virtio-net, restore also requires
`--network-profile portable`; the snapshot's profile and canonical egress
Expand Down
4 changes: 3 additions & 1 deletion Guide/src/user_guide/openvmm/snapshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -432,7 +432,9 @@ host paths, kinds, target, and modes, the same
`--mount-deny`, `--mount-allow`, and `--mount-write` paths, and the same
`--mount-owner` mode. OpenVMM independently validates the roots and every
saved object identity before starting a vCPU. A dormant-slot snapshot may
restore without an attachment or bind one new `--mount` to the slot.
restore without an attachment or bind one new `--mount` to the slot, and a
platform snapshot may instead bind a new `--mount-aggregate`, which OpenVMM
validates as at a cold boot.
For a new attachment, the resumed guest explicitly mounts tag `microvm`; the
cold-boot mount hook does not run again.

Expand Down
9 changes: 7 additions & 2 deletions openvmm/openvmm_entry/src/cli_args/microvm.rs
Original file line number Diff line number Diff line change
Expand Up @@ -483,7 +483,11 @@ pub struct MicrovmCli {
/// enter it, and it lists one directory or regular file per
/// `--mount-child`, which has its own access mode. The guest mounts the
/// `microvm` tag at GUEST_TARGET with `virtfs_aggregate=1` on its command
/// line, and is expected to bind-mount each child where it is needed.
/// line, and is expected to bind-mount each child where it is needed. A
/// platform snapshot's dormant slot may bind an aggregate on restore,
/// validated as at a cold boot; the resumed guest keeps its captured
/// command line, so it must learn of the aggregate from its host and
/// mount the `microvm` tag explicitly.
#[clap(
long = "mount-aggregate",
value_name = "GUEST_TARGET",
Expand All @@ -503,7 +507,8 @@ pub struct MicrovmCli {
/// A file child's mode applies to the whole file, which no
/// `--mount-deny`, `--mount-allow`, or `--mount-write` path may name.
/// Host paths must not overlap: a file must not lie inside a directory
/// child. A restore requires the same children, in the same order.
/// child. A snapshot that attached an aggregate requires the same
/// children, in the same order, on restore.
#[clap(
long = "mount-child",
value_name = "NAME,HOST_PATH[,ro|rw][,file]",
Expand Down
233 changes: 213 additions & 20 deletions openvmm/openvmm_entry/src/microvm/filesystem.rs
Original file line number Diff line number Diff line change
Expand Up @@ -953,7 +953,9 @@ pub(crate) fn microvm_filesystem_slot_from_snapshot(

/// Returns the effective filesystem that `request` attaches. A restore must
/// supply exactly the snapshot's filesystem, unless the snapshot's slot is
/// dormant, in which case one `--mount` may bind a new filesystem to it.
/// dormant, in which case the restore may bind a new filesystem to it, which
/// it validates as a cold boot does: one `--mount`, or, at the restore of a
/// platform snapshot, which `prepare_restore` checks, an aggregate.
pub(super) fn effective_microvm_filesystem(
request: Option<MicrovmFilesystemRequest<'_>>,
policy: MicrovmFilesystemPolicyPaths<'_>,
Expand Down Expand Up @@ -987,11 +989,9 @@ pub(super) fn effective_microvm_filesystem(
== openvmm_helpers::snapshot::microvm::MICROVM_FILESYSTEM_SLOT_VERSION,
"snapshot does not support restore-time microVM filesystem attachment"
);
// Only the dormant slot exists in the snapshot's machine.
anyhow::ensure!(
matches!(request, MicrovmFilesystemRequest::Single(_)),
"a dormant-slot snapshot can attach only a --mount on restore"
);
// The snapshot's machine has only the dormant slot, whose device and
// command line stay as captured whatever the restore binds to it, so
// the restore builds the filesystem as a cold boot does.
return microvm_filesystem_from_request(request, policy, owner).map(Some);
};
let request =
Expand Down Expand Up @@ -2006,32 +2006,225 @@ mod tests {
}

#[test]
fn restore_attaches_an_aggregate_only_where_the_snapshot_did() {
fn restore_attaches_an_aggregate_only_to_a_dormant_slot() {
let workspace = tempfile::tempdir().unwrap();
let toolcache = tempfile::tempdir().unwrap();
let children = workspace_and_toolcache(workspace.path(), toolcache.path(), "ro");
let restore = ["--restore-snapshot", "snapshot"];
let options = aggregate_options(&children, &["--restore-snapshot", "snapshot"]);

// A dormant slot binds only a single directory on restore.
let error = options_filesystem(
&aggregate_options(&children, &restore),
Some(&dormant_filesystem_contract()),
)
.unwrap_err();
assert!(error.to_string().contains("only a --mount"), "{error:#}");
// A dormant slot binds the aggregate.
let filesystem =
options_filesystem(&options, Some(&dormant_filesystem_contract())).unwrap();
assert!(filesystem.config.is_aggregate());

// A snapshot that predates the dormant slot binds no filesystem.
let error = options_filesystem(&options, Some(&network_contract())).unwrap_err();
assert!(
error
.to_string()
.contains("does not support restore-time microVM filesystem attachment"),
"{error:#}"
);

// A snapshot of a single directory requires that directory.
let error = options_filesystem(
&aggregate_options(&children, &restore),
Some(&filesystem_contract(workspace.path())),
)
.unwrap_err();
let error =
options_filesystem(&options, Some(&filesystem_contract(workspace.path()))).unwrap_err();
assert!(
error.to_string().contains("requires the --mount"),
"{error:#}"
);
}

/// Resolves the aggregate that `children` and the access-policy options
/// `policy` request with `owner`, at a cold boot and at a restore that
/// binds it to a dormant slot.
fn cold_and_dormant_aggregates(
children: &[String],
policy: &[&str],
owner: openvmm_defs::microvm::MicrovmFilesystemOwner,
) -> [anyhow::Result<EffectiveMicrovmFilesystem>; 2] {
let mut restore = policy.to_vec();
restore.extend(["--restore-snapshot", "snapshot"]);
let dormant = dormant_filesystem_contract();
[
(aggregate_options(children, policy), None),
(aggregate_options(children, &restore), Some(&dormant)),
]
.map(|(options, contract)| {
effective_microvm_filesystem(
MicrovmFilesystemRequest::from_options(&options),
MicrovmFilesystemPolicyPaths {
denied: &options.microvm.microvm_mount_deny,
allowed: &options.microvm.microvm_mount_allow,
writable: &options.microvm.microvm_mount_write,
},
owner,
contract,
)
.and_then(|filesystem| filesystem.context("the options request no filesystem"))
})
}

#[test]
fn dormant_slot_restore_attaches_an_aggregate_as_a_cold_boot_does() {
use openvmm_defs::microvm::MicrovmFilesystemAccess::ReadOnly;
use openvmm_defs::microvm::MicrovmFilesystemAccess::ReadWrite;
use openvmm_defs::microvm::MicrovmFilesystemChildKind::Directory;
use openvmm_defs::microvm::MicrovmFilesystemChildKind::File;

let workspace = policy_share();
let toolcache = tempfile::tempdir().unwrap();
let files = tempfile::tempdir().unwrap();
let settings = files.path().join("settings.json");
let output = files.path().join("output.txt");
fs_err::write(&settings, b"{}").unwrap();
fs_err::write(&output, b"").unwrap();
let children = [
format!("work,{},rw", workspace.path().display()),
format!("tools,{},ro", toolcache.path().display()),
format!("settings,{},ro,file", settings.display()),
format!("output,{},rw,file", output.display()),
];
let path = |relative: &str| workspace.path().join(relative).display().to_string();
let (logs, payloads, out, log) = (
path("logs"),
path("logs/payloads"),
path("out"),
path("build.log"),
);
let policy = [
"--mount-deny",
&logs,
"--mount-allow",
&payloads,
"--mount-write",
&out,
"--mount-write",
&log,
];
let [cold, restored] = cold_and_dormant_aggregates(&children, &policy, VMM);
let (cold, restored) = (cold.unwrap(), restored.unwrap());
assert_eq!(
restored
.config
.children
.iter()
.map(|child| (child.name.as_str(), child.kind, child.access))
.collect::<Vec<_>>(),
[
("work", Directory, ReadWrite),
("tools", Directory, ReadOnly),
("settings", File, ReadOnly),
("output", File, ReadWrite),
]
);
let work = &restored.config.children[0];
assert_eq!(work.denied_paths, ["logs"]);
assert_eq!(work.allowed_paths, ["logs/payloads"]);
assert_eq!(work.writable_paths, ["build.log", "out"]);
// The restore resolves the roots, identities, and policy of the cold
// boot.
assert_eq!(restored.config, cold.config);
assert_eq!(restored.attachment, cold.attachment);
assert_eq!(restored.children, cold.children);
}

#[test]
fn dormant_slot_restore_refuses_the_aggregates_that_a_cold_boot_refuses() {
let parent = tempfile::tempdir().unwrap();
let work = parent.path().join("work");
let nested = work.join("nested");
fs_err::create_dir_all(&nested).unwrap();
let settings = parent.path().join("settings.json");
fs_err::write(&settings, b"{}").unwrap();
let other = tempfile::tempdir().unwrap();
let outside = tempfile::tempdir().unwrap();
let directory = |name: &str, path: &Path| format!("{name},{},rw", path.display());
let file = |name: &str, path: &Path| format!("{name},{},ro,file", path.display());
let settings_path = settings.display().to_string();
let outside_path = outside.path().display().to_string();
for (children, policy, expected) in [
// Host paths that overlap.
(
vec![directory("work", &work), directory("nested", &nested)],
vec![],
"must not overlap",
),
(
vec![
directory("parent", parent.path()),
file("settings", &settings),
],
vec![],
"must not overlap",
),
// Host objects of another kind than the child's.
(
vec![format!("work,{},rw,file", work.display())],
vec![],
"not a regular file",
),
(
vec![format!("settings,{},ro", settings.display())],
vec![],
"not a plain directory",
),
// A repeated name.
(
vec![directory("same", &work), directory("same", other.path())],
vec![],
"not unique",
),
// Policy paths that no child takes.
(
vec![file("settings", &settings)],
vec!["--mount-deny", settings_path.as_str()],
"exposes the file",
),
(
vec![directory("work", &work)],
vec!["--mount-deny", outside_path.as_str()],
"outside the filesystem export roots",
),
(
vec![directory("work", &work)],
vec!["--mount-deny", "nested"],
"absolute host path",
),
] {
let [cold, restored] = cold_and_dormant_aggregates(&children, &policy, VMM);
let (cold, restored) = (cold.unwrap_err(), restored.unwrap_err());
assert!(format!("{cold:#}").contains(expected), "{cold:#}");
assert_eq!(format!("{restored:#}"), format!("{cold:#}"));
}
}

#[test]
fn dormant_slot_restore_applies_the_owner_of_a_cold_boot() {
let work = tempfile::tempdir().unwrap();
let children = [format!("work,{},rw", work.path().display())];
let [cold, restored] = cold_and_dormant_aggregates(
&children,
&[],
openvmm_defs::microvm::MicrovmFilesystemOwner::Caller,
);
// Caller ownership needs a Linux host and roots that root does not
// own, so a cold boot may refuse it here; the restore must then refuse
// it too.
match (cold, restored) {
(Ok(cold), Ok(restored)) => {
assert!(restored.config.owner.is_caller());
assert_eq!(restored.config, cold.config);
}
(Err(cold), Err(restored)) => {
assert_eq!(format!("{restored:#}"), format!("{cold:#}"));
}
(cold, restored) => {
panic!("the cold boot and the restore disagree: {cold:?} and {restored:?}")
}
}
}

#[test]
fn aggregate_restore_requires_the_same_children() {
let workspace = policy_share();
Expand Down
Loading
Loading