Skip to content

activation: keep only guest-applied settings in record v2 #1311

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
Pedro Henrique Penna (ppenna) merged 3 commits into from
Nov 7, 2026
Merged

activation: keep only guest-applied settings in record v2 #1311

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
26267bb
activation: keep only guest-applied settings in record v2
Nov 6, 2026
9eee18a
activation: align the public API snapshots with record v2
Nov 6, 2026
02d4219
activation: correct the cold-boot fixture description
Nov 6, 2026
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
61 changes: 28 additions & 33 deletions nvx-rs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -295,19 +295,16 @@ The activation record of a layered root: one bounded, versioned, non-secret
record of the settings that its activation applies, which a clone restored from
a template reads in place of its captured configuration.

An `ActivationRecord` holds the schema's `VERSION`, a clone's `RestoreSection`,
the restore's `TransactionId` and the `TemplateReference` of its template, the
template's `StoreGeneration`, a nonzero publication ID that its store assigns in
order, and the `Identity` of its key, and the `Configuration`: the `Image`,
EROFS or GPT, with the `Identity` of its binding and the UUID or disk GUID that
the guest expects; the `Upper`, a tmpfs or the scratch with its binding's
`Identity` and its `Journal` policy; the `OverlayMode`; an `Export`, a directory
or an aggregate with its plan's `Identity`, and its 1 to 4,096 mappings; the
`Network`, its policy's `Identity`, a DNS address, the listeners' `Publication`,
and a proxy endpoint without credentials; the `WorkloadView`, its hostname,
`MachineIdMode`, and `WorkloadIdentity`, whose IDs are neither 0 nor `u32::MAX`;
and the `ExpectedResources`. The other inputs of the root's assembly are
invariants of the template.
An `ActivationRecord` holds the schema's `VERSION`, 2, a clone's
`RestoreSection`, only the restore's `TransactionId`, and the `Configuration`:
the `Image`, EROFS or GPT, with the UUID or disk GUID that the guest expects;
the `Upper`, a tmpfs with its cap in percent of the VM's memory or the scratch
with its `Journal` policy; the `OverlayMode`; an `Export`, a directory or an
aggregate, and its 1 to 4,096 mappings; the `Network`, a DNS address, the
listeners' `Publication`, and a proxy endpoint without credentials; the `View`,
its hostname and `MachineIdMode`; and the `ExpectedResources`. Store, binding,
plan, policy and execution identities never enter a record. The other inputs
of the root's assembly are invariants of the template.

`View` is the view that a VM's configuration, a [`VmConfig`](#nvxhostconfig),
gives its workload: its hostname and `MachineIdMode`, without an identity, which
Expand All @@ -316,13 +313,13 @@ each execution names.
`ActivationRecord::new` refuses a configuration that `Configuration::check`
finds past a public limit, `MAX_MAPPINGS`, `MAX_HOSTNAME_BYTES`, or
`MAX_PROXY_ENDPOINT_BYTES`, which keep every record within `MAX_RECORD_BYTES`,
or with an export without mappings, mappings without an export, a UID or GID of
0 or `u32::MAX`, a proxy endpoint with credentials, or a zero size.
or with an export without mappings, mappings without an export, a tmpfs cap
outside 1 to 90 percent, a proxy endpoint with credentials, or a zero size.

`ActivationRecord::encode` writes a record's canonical encoding, its version,
then a tagged, length-prefixed field for each part in the order of their tags,
602 bytes at most, and `ActivationRecord::decode` reads exactly those bytes back
and refuses any others, naming the `Field` at fault.
424 bytes at most, and `ActivationRecord::decode` reads exactly those bytes back
and refuses any others, naming the `Field` at fault. Version 1 is refused.

`ReadyActivation` is what Ready reports once the activation applied: a clone's
transaction ID, which `ReadyActivation::of` takes from a record, and nothing
Expand Down Expand Up @@ -902,8 +899,8 @@ capture's own metadata, such as its time anchor and host, stays out of the key.

A key and a class each have one canonical, versioned encoding, whose
domain-separated SHA-256 digest is its identity, a `KeyIdentity`, which converts
to and from the `nvx::activation::Identity` by which a clone's activation record
names its template's key, or a `ClassIdentity`; the
to and from the `nvx::activation::Identity` by which a clone's lease and durable records
name its template's key, or a `ClassIdentity`; the
[conformance vectors](tests/vectors/README.md) of version 1,
`tests/vectors/template-key-v1.txt`, pin both encodings and identities. The
key's encoding, version 1, leaves the network policy out, since templates
Expand All @@ -930,7 +927,7 @@ its directories and files.

Four namespaces stay apart: the `nvx::activation::StoreGeneration`, the host's
publication ID, which the index assigns in the order of publication and never
twice, and by which a clone's activation record names its template; the
twice, and by which a clone's lease and durable records name its template; the
bound-block `StorageGeneration` of a capture, which belongs to the storage
owner; the time lineage counter of the time contract; and the VM generation ID,
which the store never records.
Expand Down Expand Up @@ -990,22 +987,20 @@ as those above a clone's block devices must; and a fresh capability.

It builds the clone's activation record, `ClonePlan::activation`, which the
clone's guest applies in place of the configuration that the template captured,
from the request's `WorkloadView`, overlay mode, journal policy, and bound of a
from the request's `View`, overlay mode, journal policy, and bound of a
GPT disk's first partition, and from the checked inputs: a restore section with
a fresh transaction ID of 16 random bytes and the lease's `TemplateReference`;
the image, an EROFS layer or a GPT disk, as its binding names it, with its
binding's identity and the filesystem UUID or disk GUID that the adapter's plan
a fresh transaction ID of 16 random bytes alone;
the image, an EROFS layer or a GPT disk, as its binding names it, with the
filesystem UUID or disk GUID that the adapter's plan
expects of it, and for a GPT disk the bound of its first partition, whose
partition table the guest checks with `nvx::gpt` as at a cold launch; a tmpfs,
or the scratch image's binding identity with the journal policy; the export, an
aggregate, with its plan's identity, and its mappings, the plan's binds, from 1
partition table the guest checks with `nvx::gpt` as at a cold launch; a tmpfs
capped at half of the VM's memory, or the scratch image with the journal policy;
the export, an aggregate, and its mappings, the plan's binds, from 1
to 4,096, or no export and no mappings, which leaves the slot dormant; the
clone's network, with its identity, the DNS server that OpenVMM serves the guest
clone's network, the DNS server that OpenVMM serves the guest
at a gateway under its policy, if any, whether the guest publishes its
listeners, as under a policy that allows ingress or host-loopback access both
ways, and the guest's proxy URL; and the processor and memory targets. The
identity of a binding, of an export plan, or of a network is the SHA-256 digest
of a domain and of its serde form, never of a file's content.
ways, and the guest's proxy URL; and the processor and memory targets.

The image must present the logical and physical block sizes of the template's
placeholder and be no longer than it, since a restore presents every clone's
Expand Down Expand Up @@ -1629,7 +1624,7 @@ with `BLKRRPART`, since the kernel created the block devices of partitions for
the template's placeholder. Whatever the image, it requires a fresh upper, whose
`upper` and `work` directories are missing or empty, in a bounded check that
reads no file, while a cold sandbox's scratch keeps its upper across boots. It
ignores the record's workload identity, if it has one: each execution names its
uses no execution identity from the record, which carries none: each execution names its
own identity, which `Entry::check` checks, as in a sandbox without a workload
identity at a cold boot. With the record's generated machine ID, it then
generates one, once, with `MachineId::generate`, after the repair's reseed, so
Expand Down Expand Up @@ -2984,7 +2979,7 @@ sides of every record, frame, and payload: the codec decodes each vector of
accepts or refuses OpenVMM's vectors and cases of the `NVXS` session as they
say, and, on Linux, the guest's listener announcements match
`tests/vectors/nvxl-v1.txt`. The activation codecs decode each record and
Ready activation of `tests/vectors/activation-v1.txt` to its values, encode
Ready activation of `tests/vectors/activation-v2.txt` to its values, encode
them to its bytes, and refuse its invalid bytes. Property tests check that
records and activation records round-trip, that the activation record and
Ready activation decoders accept only canonical encodings, and that the
Expand Down
23 changes: 5 additions & 18 deletions nvx-rs/public-api/linux.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,8 @@ variant nvx::activation::ActivationError::MissingField
field nvx::activation::ActivationError::MissingField::0
variant nvx::activation::ActivationError::ProxyEndpoint
variant nvx::activation::ActivationError::Ready
variant nvx::activation::ActivationError::TmpfsMemoryPercent
field nvx::activation::ActivationError::TmpfsMemoryPercent::0
variant nvx::activation::ActivationError::TooLong
field nvx::activation::ActivationError::TooLong::0
variant nvx::activation::ActivationError::TooManyMappings
Expand All @@ -119,7 +121,6 @@ variant nvx::activation::ActivationError::Version
field nvx::activation::ActivationError::Version::0
variant nvx::activation::ActivationError::WithoutNetwork
field nvx::activation::ActivationError::WithoutNetwork::0
variant nvx::activation::ActivationError::WorkloadIdentity
struct nvx::activation::ActivationRecord
method nvx::activation::ActivationRecord::configuration
method nvx::activation::ActivationRecord::decode
Expand All @@ -136,13 +137,12 @@ field nvx::activation::Configuration::network
field nvx::activation::Configuration::overlay
field nvx::activation::Configuration::resources
field nvx::activation::Configuration::upper
field nvx::activation::Configuration::workload
field nvx::activation::Configuration::view
struct nvx::activation::ExpectedResources
field nvx::activation::ExpectedResources::cpus
field nvx::activation::ExpectedResources::memory
struct nvx::activation::Export
field nvx::activation::Export::kind
field nvx::activation::Export::plan
enum nvx::activation::ExportKind
variant nvx::activation::ExportKind::Aggregate
variant nvx::activation::ExportKind::Directory
Expand All @@ -161,7 +161,6 @@ variant nvx::activation::Field::Proxy
variant nvx::activation::Field::Resources
variant nvx::activation::Field::Restore
variant nvx::activation::Field::Upper
variant nvx::activation::Field::WorkloadIdentity
method nvx::activation::Field::from_tag
method nvx::activation::Field::tag
struct nvx::activation::Identity
Expand All @@ -170,13 +169,10 @@ method nvx::activation::Identity::as_bytes
method nvx::activation::Identity::from_bytes
enum nvx::activation::Image
variant nvx::activation::Image::Erofs
field nvx::activation::Image::Erofs::binding
field nvx::activation::Image::Erofs::uuid
variant nvx::activation::Image::Gpt
field nvx::activation::Image::Gpt::binding
field nvx::activation::Image::Gpt::disk_guid
field nvx::activation::Image::Gpt::first_partition_bound
method nvx::activation::Image::binding
method nvx::activation::Image::expected
method nvx::activation::Image::format
enum nvx::activation::Journal
Expand All @@ -191,7 +187,6 @@ variant nvx::activation::MachineIdMode::Generated
variant nvx::activation::MachineIdMode::Image
struct nvx::activation::Network
field nvx::activation::Network::dns
field nvx::activation::Network::policy
field nvx::activation::Network::proxy
field nvx::activation::Network::publication
enum nvx::activation::OverlayMode
Expand All @@ -208,7 +203,6 @@ method nvx::activation::ReadyActivation::encode
method nvx::activation::ReadyActivation::of
field nvx::activation::ReadyActivation::transaction
struct nvx::activation::RestoreSection
field nvx::activation::RestoreSection::template
field nvx::activation::RestoreSection::transaction
struct nvx::activation::StoreGeneration
method nvx::activation::StoreGeneration::get
Expand All @@ -222,20 +216,13 @@ method nvx::activation::TransactionId::as_bytes
method nvx::activation::TransactionId::from_bytes
enum nvx::activation::Upper
variant nvx::activation::Upper::Scratch
field nvx::activation::Upper::Scratch::binding
field nvx::activation::Upper::Scratch::journal
variant nvx::activation::Upper::Tmpfs
field nvx::activation::Upper::Tmpfs::max_memory_percent
const nvx::activation::VERSION
struct nvx::activation::View
field nvx::activation::View::hostname
field nvx::activation::View::machine_id
struct nvx::activation::WorkloadIdentity
field nvx::activation::WorkloadIdentity::gid
field nvx::activation::WorkloadIdentity::uid
struct nvx::activation::WorkloadView
field nvx::activation::WorkloadView::hostname
field nvx::activation::WorkloadView::identity
field nvx::activation::WorkloadView::machine_id
mod nvx::contract
const nvx::contract::BOOT_CONTRACT_VERSION
const nvx::contract::CONTROL_CONTRACT_REVISION
Expand Down Expand Up @@ -2880,7 +2867,7 @@ field nvx::host::template::CloneRequest::overlay
field nvx::host::template::CloneRequest::policy_revision
field nvx::host::template::CloneRequest::processors
field nvx::host::template::CloneRequest::scratch
field nvx::host::template::CloneRequest::workload
field nvx::host::template::CloneRequest::view
enum nvx::host::template::CloneUpper
variant nvx::host::template::CloneUpper::Scratch
field nvx::host::template::CloneUpper::Scratch::0
Expand Down
23 changes: 5 additions & 18 deletions nvx-rs/public-api/windows.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -108,6 +108,8 @@ variant nvx::activation::ActivationError::MissingField
field nvx::activation::ActivationError::MissingField::0
variant nvx::activation::ActivationError::ProxyEndpoint
variant nvx::activation::ActivationError::Ready
variant nvx::activation::ActivationError::TmpfsMemoryPercent
field nvx::activation::ActivationError::TmpfsMemoryPercent::0
variant nvx::activation::ActivationError::TooLong
field nvx::activation::ActivationError::TooLong::0
variant nvx::activation::ActivationError::TooManyMappings
Expand All @@ -119,7 +121,6 @@ variant nvx::activation::ActivationError::Version
field nvx::activation::ActivationError::Version::0
variant nvx::activation::ActivationError::WithoutNetwork
field nvx::activation::ActivationError::WithoutNetwork::0
variant nvx::activation::ActivationError::WorkloadIdentity
struct nvx::activation::ActivationRecord
method nvx::activation::ActivationRecord::configuration
method nvx::activation::ActivationRecord::decode
Expand All @@ -136,13 +137,12 @@ field nvx::activation::Configuration::network
field nvx::activation::Configuration::overlay
field nvx::activation::Configuration::resources
field nvx::activation::Configuration::upper
field nvx::activation::Configuration::workload
field nvx::activation::Configuration::view
struct nvx::activation::ExpectedResources
field nvx::activation::ExpectedResources::cpus
field nvx::activation::ExpectedResources::memory
struct nvx::activation::Export
field nvx::activation::Export::kind
field nvx::activation::Export::plan
enum nvx::activation::ExportKind
variant nvx::activation::ExportKind::Aggregate
variant nvx::activation::ExportKind::Directory
Expand All @@ -161,7 +161,6 @@ variant nvx::activation::Field::Proxy
variant nvx::activation::Field::Resources
variant nvx::activation::Field::Restore
variant nvx::activation::Field::Upper
variant nvx::activation::Field::WorkloadIdentity
method nvx::activation::Field::from_tag
method nvx::activation::Field::tag
struct nvx::activation::Identity
Expand All @@ -170,13 +169,10 @@ method nvx::activation::Identity::as_bytes
method nvx::activation::Identity::from_bytes
enum nvx::activation::Image
variant nvx::activation::Image::Erofs
field nvx::activation::Image::Erofs::binding
field nvx::activation::Image::Erofs::uuid
variant nvx::activation::Image::Gpt
field nvx::activation::Image::Gpt::binding
field nvx::activation::Image::Gpt::disk_guid
field nvx::activation::Image::Gpt::first_partition_bound
method nvx::activation::Image::binding
method nvx::activation::Image::expected
method nvx::activation::Image::format
enum nvx::activation::Journal
Expand All @@ -191,7 +187,6 @@ variant nvx::activation::MachineIdMode::Generated
variant nvx::activation::MachineIdMode::Image
struct nvx::activation::Network
field nvx::activation::Network::dns
field nvx::activation::Network::policy
field nvx::activation::Network::proxy
field nvx::activation::Network::publication
enum nvx::activation::OverlayMode
Expand All @@ -208,7 +203,6 @@ method nvx::activation::ReadyActivation::encode
method nvx::activation::ReadyActivation::of
field nvx::activation::ReadyActivation::transaction
struct nvx::activation::RestoreSection
field nvx::activation::RestoreSection::template
field nvx::activation::RestoreSection::transaction
struct nvx::activation::StoreGeneration
method nvx::activation::StoreGeneration::get
Expand All @@ -222,20 +216,13 @@ method nvx::activation::TransactionId::as_bytes
method nvx::activation::TransactionId::from_bytes
enum nvx::activation::Upper
variant nvx::activation::Upper::Scratch
field nvx::activation::Upper::Scratch::binding
field nvx::activation::Upper::Scratch::journal
variant nvx::activation::Upper::Tmpfs
field nvx::activation::Upper::Tmpfs::max_memory_percent
const nvx::activation::VERSION
struct nvx::activation::View
field nvx::activation::View::hostname
field nvx::activation::View::machine_id
struct nvx::activation::WorkloadIdentity
field nvx::activation::WorkloadIdentity::gid
field nvx::activation::WorkloadIdentity::uid
struct nvx::activation::WorkloadView
field nvx::activation::WorkloadView::hostname
field nvx::activation::WorkloadView::identity
field nvx::activation::WorkloadView::machine_id
mod nvx::contract
const nvx::contract::BOOT_CONTRACT_VERSION
const nvx::contract::CONTROL_CONTRACT_REVISION
Expand Down Expand Up @@ -1802,7 +1789,7 @@ field nvx::host::template::CloneRequest::overlay
field nvx::host::template::CloneRequest::policy_revision
field nvx::host::template::CloneRequest::processors
field nvx::host::template::CloneRequest::scratch
field nvx::host::template::CloneRequest::workload
field nvx::host::template::CloneRequest::view
enum nvx::host::template::CloneUpper
variant nvx::host::template::CloneUpper::Scratch
field nvx::host::template::CloneUpper::Scratch::0
Expand Down
Loading
Loading