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
33 changes: 18 additions & 15 deletions Guide/src/dev_guide/snapshot_format.md
Original file line number Diff line number Diff line change
Expand Up @@ -31,17 +31,20 @@ 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 default format is a local machine-state contract, not an authenticated
container. Every snapshot receives the same regular-file, no-follow/no-reparse,
bounded decoding, exact-length, inventory, and machine-contract validation,
but the on-disk format does not authenticate same-length payload changes.
By default, paired capture records SHA-256 and exact length for `scratch.img`,
because guest RAM and a mounted writable filesystem must be restored as one
exact pair. The format also permits an explicit `generation` identity for all
bound sandbox blocks. Generation identity is a caller-authenticated immutable
storage version, not a byte digest; OpenVMM validates role, size, geometry, and
the shared generation without scanning block contents. Export or transport
layers must provide broader integrity and authentication outside this format.
The format is a local machine-state contract, not an authenticated container.
Every snapshot receives the same regular-file, no-follow/no-reparse, bounded
decoding, exact-length, inventory, and machine-contract validation, but the
on-disk format does not authenticate same-length payload changes. A
`workload-start` or `instance-checkpoint` snapshot binds its sandbox blocks,
the read-only layers and the paired `scratch.img`, which guest RAM and a
mounted writable filesystem must restore as one exact pair, to one
`generation` identity: a caller-authenticated immutable storage generation,
not a byte digest. Neither capture nor restore reads a block to identify it:
OpenVMM validates role, size, geometry, and the shared generation, and a
restore requires the generation that the snapshot recorded. Restore rejects
the `sha256` block identity of earlier releases, whose snapshots must be
recaptured. Export or transport layers must provide broader integrity and
authentication outside this format.

The optional microVM network contract stores the SHA-256 digest of its bound
egress policy in encoding version 1, which covers the static IPv4 and IPv6
Expand Down Expand Up @@ -98,10 +101,10 @@ The microVM block contract records every fixed role, access mode, geometry,
identity kind, identity, and paired-scratch restore mode. A paired capture
copies the exact opened writable scratch handle into the same staging
directory after device queues drain and publishes it atomically with VM state.
`sha256` identity verifies bytes before publication and restore. `generation`
identity instead requires every bound block to carry the same nonzero
caller-authenticated storage generation and performs structural and exact-size
validation without whole-file rehashing.
Every bound block carries the same nonzero caller-authenticated storage
generation, and publication and restore check `scratch.img` structurally and
by exact size, without reading it to verify its content. A platform capture
binds no block, so its read-only layers are `unbound`.

Paired scratch defaults to `private-copy`, which preserves existing behavior
and may use a reflink or sparse copy. `copy-on-write` requires a filesystem
Expand Down
45 changes: 29 additions & 16 deletions Guide/src/reference/openvmm/management/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -495,14 +495,17 @@ describes the source definitions.
a snapshot without a tier.

For sandbox-block snapshots, restore repeats the read-only `distro`
`--microvm-sandbox-block` argument. Its role, access, geometry, and SHA-256
must match the manifest, with two exceptions for a platform snapshot: its
`distro` layer is unbound, and it keeps the captured capacity over an image
that may be shorter. Such an image must have the
`--microvm-sandbox-block` argument. Its role, access, and geometry must
match the manifest, and a `workload-start` or `instance-checkpoint`
snapshot, which binds its blocks to a storage generation, also requires that
generation through `--restore-generation-id`; OpenVMM never reads a block to
identify it. A platform snapshot has two exceptions: its `distro` layer is
unbound, and it keeps the captured capacity over an image that may be
shorter. Such an image must have the
captured logical and physical block sizes, reads past its end return zeros,
and OpenVMM never resizes, pads, or writes it; a longer image is rejected.
A paired snapshot supplies scratch internally from
a verified process-private copy of `scratch.img`; passing another scratch is
a process-private copy of `scratch.img`; passing another scratch is
rejected. A fresh-scratch snapshot instead requires a writable scratch
argument with matching geometry, or `--restore-absent-scratch`.

Expand Down Expand Up @@ -591,6 +594,14 @@ 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-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
to the generation that its capture recorded, and its restore requires the
same one: OpenVMM rejects a missing or different generation before it
materializes scratch or starts a vCPU. A platform snapshot binds no block, so
its restore checks no generation. OpenVMM rejects the option for a cold boot
and for a snapshot without sandbox blocks.
* `--restore-gate-timeout-ms <MILLISECONDS>`: Bound microVM guest repair and
gate acknowledgement after restore. The default is 60000 milliseconds.
* `--cpu-profile <ID>`: Select the microVM's pinned CPU profile, `auto`
Expand Down Expand Up @@ -619,12 +630,13 @@ describes the source definitions.
* `--snapshot-tier <TIER>`: Required for snapshot capture with sandbox blocks. Choose
`platform`, `workload-start`, or `instance-checkpoint`. The first two are
reusable clone policies; instance checkpoints use single-use resume policy.
* `--snapshot-block-identity <MODE>`: Select `sha256` (the default) or
`generation`. SHA-256 computes and verifies every bound block. Generation
mode requires `--snapshot-generation-id <32-HEX-DIGITS>` and records that
caller-authenticated immutable storage generation instead of scanning block
bytes. The caller must keep the generation bound to the exact immutable
artifacts supplied at restore.
* `--snapshot-generation-id <32-HEX-DIGITS>`: Supply the immutable storage
generation of the capture's sandbox blocks. A `workload-start` or
`instance-checkpoint` capture requires it and records it as the identity of
every read-only layer and of the paired scratch, instead of reading them; a
restore must state it again with `--restore-generation-id`. A platform
capture binds no block and records none. The storage owner must keep the
generation bound to the exact immutable artifacts supplied at restore.
* `--snapshot-scratch-restore-mode <MODE>`: Record `private-copy`,
`copy-on-write`, or `direct-claimed` for paired scratch. Private copy is the
default and may fall back to sparse copying. Copy-on-write is available only
Expand All @@ -635,16 +647,17 @@ describes the source definitions.

A committed snapshot contains `manifest.bin`, `state.bin`, `memory.bin`, and
optionally the manifest-declared `scratch.img`. Restore rejects unknown files,
symlinks, malformed or oversized data, length or applicable scratch-digest
mismatches, and incompatible machine contracts before starting a vCPU.
symlinks, malformed or oversized data, length mismatches, a missing or
different storage generation, the `sha256` block identity of earlier releases,
and incompatible machine contracts before starting a vCPU.
`memory.bin` uses a private writable copy-on-write mapping. Paired scratch uses
the materialization policy recorded at capture; clone-policy snapshots never
attach the source artifact writable, while direct attachment requires an
atomic single-use resume claim.

Versions 3 through 6 do not embed or validate checksums for `state.bin` or `memory.bin`;
legacy version 2 checksum fields are accepted without re-hashing their
payloads. This format does not detect same-length payload changes,
The format embeds no checksums of `state.bin`, `memory.bin`, `scratch.img`, or
the read-only layers, and OpenVMM never reads them to verify their contents.
This format does not detect same-length payload changes,
authenticate, or encrypt a snapshot. Treat all three artifacts as sensitive
guest state and protect the directory with host access controls.
* `--memory <SPEC>`: Configure guest RAM. Defaults to `size=1G`.
Expand Down
44 changes: 24 additions & 20 deletions Guide/src/user_guide/openvmm/snapshots.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,14 +42,16 @@ with sandbox blocks additionally requires
workload-start snapshots are reusable clones; instance checkpoints are
single-use resumes.

Sandbox-block capture defaults to whole-file SHA-256 identity and private
scratch copying. Storage owners may opt into
`--snapshot-block-identity generation --snapshot-generation-id <32-HEX-DIGITS>`
when an authenticated immutable generation already binds the supplied files.
This avoids capture- and restore-time block scans; it does not authenticate
bytes by itself. `--snapshot-scratch-restore-mode` records `private-copy`,
reflink-only `copy-on-write` for workload-start clones, or `direct-claimed`
for instance checkpoints.
A workload-start or instance-checkpoint capture binds its read-only layers and
paired scratch to the storage generation that
`--snapshot-generation-id <32-HEX-DIGITS>` supplies, and each restore of the
snapshot states that generation again with `--restore-generation-id`. OpenVMM
never reads a block to identify it, and the generation does not authenticate
bytes by itself: the storage owner must keep it immutable and bound to the
exact files. A platform capture binds no block and needs no generation.
Paired scratch defaults to private copying; `--snapshot-scratch-restore-mode`
records `private-copy`, reflink-only `copy-on-write` for workload-start clones,
or `direct-claimed` for instance checkpoints.

```admonish warning
Automatically allocated microVM RAM and the snapshot destination are on the
Expand Down Expand Up @@ -197,8 +199,10 @@ repair must not wait for a virtio-fs reply. The acknowledgement is bounded by
host can connect while input is gated, but OpenVMM reads its authentication
only after the release, so its `--microvm-control-auth-timeout-ms` deadline
starts over when the gate releases. Platform manifests
leave read-only layer identities unbound, while later tiers require exact image
identities. A platform restore also presents the captured capacity of its
leave read-only layer identities unbound, while later tiers bind every block
to the storage generation of their capture, which the restore must state with
`--restore-generation-id`. A platform restore also presents the captured
capacity of its
`distro` block before any vCPU runs, so one platform snapshot serves images of
any length up to that capacity. An image with the captured logical and
physical block sizes may be shorter, and reads past its end, including the tail
Expand Down Expand Up @@ -325,16 +329,16 @@ target. This is not a post-readiness hotplug API and cannot add VPs absent
from the saved topology.

```admonish warning
Snapshots do not contain or validate embedded checksums for
`state.bin` or `memory.bin`. Restore still requires regular files, bounded
manifest and state decoding, exact artifact lengths, and a compatible machine
contract, but same-length payload changes are not detected. Paired `scratch.img` always
has an exact length and uses either the default SHA-256 identity or an explicit
caller-authenticated storage generation. Generation mode avoids reading the
file solely for verification and therefore relies on the storage owner to keep
that generation immutable and correctly bound. Protect snapshot directories
with host access controls. Integrity or authentication for export and
transport must be supplied outside the default snapshot format.
Snapshots do not contain or validate checksums of `state.bin`, `memory.bin`,
`scratch.img`, or the read-only layers. Restore still requires regular files,
bounded manifest and state decoding, exact artifact and block lengths, and a
compatible machine contract, but same-length payload changes are not detected.
The layers and paired `scratch.img` that a snapshot binds share one
caller-authenticated storage generation, which OpenVMM never reads a block to
verify, so it relies on the storage owner to keep that generation immutable and
correctly bound. Protect snapshot directories with host access controls.
Integrity or authentication for export and transport must be supplied outside
the snapshot format.
```

```admonish note
Expand Down
Loading
Loading