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: 13 additions & 3 deletions Guide/src/reference/openvmm/management/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -521,9 +521,10 @@ describes the source definitions.
Every microVM restore makes the restore packet available on the private
portb restore channel. The packet carries 64 bytes of fresh entropy, the
online-VP target, the memory-expansion ranges, the downtime, the TSC rate
deviation, and, at a restore that replaces the network policy of a
snapshot without a tier, the network settings of the restore's policy; the
guest must consume it and explicitly reseed its RNG.
deviation, at a restore that replaces the network policy of a snapshot
without a tier, the network settings of the restore's policy, and, at a
platform restore with `--restore-activation-record`, the clone's activation
record; the guest must consume it and explicitly reseed its RNG.
[Snapshots](../../../user_guide/openvmm/snapshots.md) documents its format,
the portb status bits, and the time sample.
Every microVM portb device also reports generation-ID support in status bit
Expand Down Expand Up @@ -597,6 +598,15 @@ describes the source definitions.
clone from its host, and the guest of a snapshot without a tier from the
restore packet, which carries them, and whose restore gates host input until
the guest acknowledges that it applied them.
* `--restore-activation-record <PATH>`: End the restore packet of a platform
snapshot's clone with the bytes of this file, the clone's activation record,
which gives the clone the settings of its own launch. The file holds 1 to
1024 bytes, which OpenVMM reads before any vCPU runs and passes to the guest
without interpreting them, so they must carry no secret. The restore gates
host input until the guest acknowledges it, which the guest does once it has
read the packet. OpenVMM rejects the option before any vCPU starts for a
cold boot, for a snapshot of another tier or without a tier, and for a file
that is empty or longer than 1024 bytes.
* `--restore-generation-id <32-HEX-DIGITS>`: State the immutable storage
generation of this restore's sandbox blocks. A `workload-start` or
`instance-checkpoint` snapshot binds its read-only layers and paired scratch
Expand Down
1 change: 1 addition & 0 deletions Guide/src/reference/openvmm/management/grpc.md
Original file line number Diff line number Diff line change
Expand Up @@ -289,6 +289,7 @@ option.
| `MicrovmSnapshotConfig.restore_generation_id` | `--restore-generation-id` |
| `MicrovmSnapshotConfig.restore_absent_scratch` | `--restore-absent-scratch` |
| `MicrovmSnapshotConfig.restore_network_policy` | `--restore-network-policy` |
| `MicrovmSnapshotConfig.restore_activation_record_path` | `--restore-activation-record` |

A string field takes its option's syntax: `MicrovmNetwork.address` is
`IPv4/PREFIX`, such as `10.0.0.2/24`, each egress rule is
Expand Down
23 changes: 18 additions & 5 deletions Guide/src/user_guide/openvmm/snapshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -256,7 +256,8 @@ from the data port. Its 24-byte little-endian header holds:
- the magic `OVR` and the version;
- flags: bit 0, the downtime came from host UTC; bit 1, a memory target;
bit 2, the guest must acknowledge the restore through port `0x605`; bit 3,
a test hook is active; bit 4, the packet carries network settings;
a test hook is active; bit 4, the packet carries network settings; bit 5,
the packet ends with an activation record;
- the online-VP target (0 for none), the memory-range count, and the network
byte;
- the generation counter (`u32`), which is 0 at cold boot and one more than
Expand All @@ -265,10 +266,11 @@ from the data port. Its 24-byte little-endian header holds:
- the downtime in nanoseconds (`u64`).

The `(u64 GPA start, u64 length)` memory ranges, 64 bytes of fresh entropy, and
a 16-byte DNS server follow the header. Status bits 2, 3, and 4 report an
online-VP target, a memory target, and one or more memory ranges, so a
zero-range target can skip post-restore repair. The packet carries no host UTC:
the guest sets its clock from a time sample.
a 16-byte DNS server follow the header, and then, with flag bit 5, the
activation record: its length (`u32`), then its bytes. Status bits 2, 3, and 4
report an online-VP target, a memory target, and one or more memory ranges, so
a zero-range target can skip post-restore repair. The packet carries no host
UTC: the guest sets its clock from a time sample.

A restore whose `--restore-network-policy` replaces the network policy of a
snapshot without a tier sets flag bit 4: the packet carries the network
Expand All @@ -283,6 +285,17 @@ acknowledgement, which the guest gives once it has applied the settings. Every
other restore, a platform clone's included, leaves flag bit 4 clear and the
network byte and DNS server zero.

A platform restore with `--restore-activation-record <PATH>` sets flag bit 5:
the packet ends with the bytes of that file, 1 to 1024 of them, the clone's
activation record, which gives the clone the settings of its own launch.
OpenVMM reads the file before any vCPU runs, and passes its bytes to the guest
without interpreting them, so they must carry no secret. Such a restore
requires the guest's acknowledgement, which the guest gives once it has read
the packet. Every other restore leaves flag bit 5 clear, and its packet ends
with the DNS server, as before the flag. A guest that predates the flag
refuses a packet that sets it, whose bit 5 it reserves, rather than ignore its
record.

Status bit 6 advertises the time sample. Writing `0xa7` to the status port
latches a 48-byte little-endian sample, version 1:

Expand Down
79 changes: 78 additions & 1 deletion openvmm/openvmm_entry/src/cli_args/microvm.rs
Original file line number Diff line number Diff line change
Expand Up @@ -313,6 +313,16 @@ pub struct MicrovmCli {
#[clap(long, requires = "restore_snapshot")]
pub restore_network_policy: bool,

/// Hand the guest of a platform snapshot's clone the bytes of this file,
/// its activation record, at the end of its restore packet.
///
/// The record holds 1 to 1024 bytes, which OpenVMM reads before any vCPU
/// runs and passes to the guest without interpreting them, so they must
/// carry no secret. The restore gates host input until the guest has
/// read the packet and acknowledged the restore.
#[clap(long, value_name = "PATH", requires = "restore_snapshot")]
pub restore_activation_record: Option<PathBuf>,

/// Immutable storage generation of the sandbox blocks of this restore.
///
/// Required to restore a `workload-start` or `instance-checkpoint`
Expand Down Expand Up @@ -822,13 +832,14 @@ impl Options {
&& self.microvm.restore_memory.is_none()
&& !self.microvm.restore_absent_scratch
&& !self.microvm.restore_network_policy
&& self.microvm.restore_activation_record.is_none()
&& self.microvm.restore_generation_id.is_none()
&& self.microvm.memory_capacity.is_none()
&& self.microvm.snapshot_generation_id.is_none()
&& self.microvm.snapshot_scratch_restore_mode.is_none()
&& self.microvm.microvm_control_console.is_none()
&& !self.microvm.microvm_control_auth_stdin,
"--network-profile, --net-tap, --mount, --mount-aggregate, --microvm-sandbox-block, --microvm-workload-identity, --microvm-lifecycle, --microvm-control-console, --microvm-control-auth-stdin, --restore-processors, --restore-memory, --restore-absent-scratch, --restore-network-policy, --restore-generation-id, --memory-capacity, snapshot block policy, and microVM network policy require a microVM machine"
"--network-profile, --net-tap, --mount, --mount-aggregate, --microvm-sandbox-block, --microvm-workload-identity, --microvm-lifecycle, --microvm-control-console, --microvm-control-auth-stdin, --restore-processors, --restore-memory, --restore-absent-scratch, --restore-network-policy, --restore-activation-record, --restore-generation-id, --memory-capacity, snapshot block policy, and microVM network policy require a microVM machine"
);
return Ok(());
}
Expand Down Expand Up @@ -952,6 +963,10 @@ impl Options {
self.restore_snapshot.is_some() || !self.microvm.restore_network_policy,
"--restore-network-policy requires --restore-snapshot"
);
anyhow::ensure!(
self.restore_snapshot.is_some() || self.microvm.restore_activation_record.is_none(),
"--restore-activation-record requires --restore-snapshot"
);
anyhow::ensure!(
self.restore_snapshot.is_some() || self.microvm.restore_generation_id.is_none(),
"--restore-generation-id requires --restore-snapshot"
Expand Down Expand Up @@ -1841,6 +1856,68 @@ mod tests {
assert!(standard.validate_microvm_options().is_err());
}

#[cfg(guest_arch = "x86_64")]
#[test]
fn test_microvm_restore_activation_record_requires_a_microvm_restore() {
let restore = Options::try_parse_from([
"openvmm",
"--machine",
"microvm",
"--restore-snapshot",
"snapshot",
"--restore-activation-record",
"record",
])
.unwrap();
restore.validate_microvm_options().unwrap();
assert_eq!(
restore.microvm.restore_activation_record.as_deref(),
Some(std::path::Path::new("record"))
);

// A cold boot has no restore packet.
assert!(
Options::try_parse_from([
"openvmm",
"--machine",
"microvm",
"--restore-activation-record",
"record",
])
.is_err()
);
// Clap accepts it when --snapshot-destination, which conflicts with
// --restore-snapshot, lifts the requirement, so the validation refuses
// it.
let cold_boot = Options::try_parse_from([
"openvmm",
"--machine",
"microvm",
"--snapshot-destination",
"snapshot",
"--restore-activation-record",
"record",
])
.unwrap();
assert_eq!(
cold_boot
.validate_microvm_options()
.unwrap_err()
.to_string(),
"--restore-activation-record requires --restore-snapshot"
);
// Nor does a standard machine.
let standard = Options::try_parse_from([
"openvmm",
"--restore-snapshot",
"snapshot",
"--restore-activation-record",
"record",
])
.unwrap();
assert!(standard.validate_microvm_options().is_err());
}

#[cfg(guest_arch = "x86_64")]
#[test]
fn test_microvm_sandbox_block_parser_and_validation() {
Expand Down
Loading
Loading