You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
doc: describe the managed layered root and platform-clone activation - #591
This updates the architecture guide with the target design for the shared image-backed sandbox runtime tracked by #535 and its current sub-issues. It defines the cold image-backed path and the common host and guest library contracts, and it also records the platform-clone design that will move to a separate platform-clone meta issue when that issue is filed. The guide describes the target rather than the current implementation. Refs #535.
Changes
Change
Sections
Issues
Shared host and guest libraries and compatibility contracts. External orchestrators and external guest agents use adapters around shared libraries instead of reimplementing root planning, mappings, execution, and supervision. The nvx-rs adapter API is guarded by a public-API check, and the guide defines the runtime-store format, runtime identity, live-upgrade boundary, and same-host-boot reattach rule.
Managed layered root. The layered root becomes a managed root assembled before readiness. It accepts host mapping tables, gives each execution a child cgroup, and uses shared host and guest libraries. NVX speaks NVXC v2 over NVXS; other adapters may use their own application framing and admission policy. The layered root never creates workload accounts.
Image verification and root assembly.distro is either EROFS or a primary-GPT image with opaque metadata in partition 1, which the adapter parses, and ordered read-only ext4 lowers in later partitions. Validation is bounded, expected identities are optional, kernel partitions must match validated entries, and the overlay uses one explicit option set with a safe choice for untrusted lower attributes. The RAM upper is selected by exactly one nvx_overlay_upper=ramfs token: a tmpfs at the kernel's default size, with no scratch block.
Cold launch planning. Image-format tokens remove probing fallback, nested mapping access is checked consistently, and the effective kernel command line is limited to 2,048 bytes including NUL, with a 1,024-byte caller budget. Cold mappings retain provisioned identities and recheck them at start; opened-object receipts remain restore-only.
Workload identity and layered-root isolation. Adapters select UID, GID, groups, account mode, machine-ID mode, hostname, and capabilities within library rules. Capabilities use a fixed allowlist, non-root gets none, and no_new_privs is mandatory. Layered-root executions move the root over /, receive private mount, PID, and UTS namespaces, and get restricted /dev and /proc views. Listener-announcement authenticity now follows from the capability, sysctl, and read-only /proc/sys rules.
NVXC v2 execution and admission.READY reports the application version, build ID, root profile, and layered-root activation identity. Hosts validate it before mappings or execution. NVXC streams stdin, stdout, and stderr with separate bounded credits and no total output cap, defines bounded output draining and settlement, and runs one execution at a time. NVX adds a FIFO of eight waiters, a 60-second default wait, stable queue errors, and a non-escalating CLI Stop policy.
Platform-clone activation. A platform template may leave the image unbound, use a shorter placeholder layer, capture the RAM-backed layout before root assembly, and bind an aggregate to a dormant filesystem slot at restore. Restore packet v5 carries a bounded activation record. Guest repair validates it before acknowledgement, then assembles the root, applies restore-time settings, reports readiness, and fails closed before any workload runs. Generated machine IDs are recreated with getrandom after reseeding; image machine IDs remain unchanged.
Network policy for platform clones. Only a platform template captured with a deny-all policy may receive a new policy. The endpoint installs it before a restored processor runs, while the activation record supplies guest DNS and ingress settings. Other snapshots retain the same-policy rule.
Restore attachment identity. Restore may verify expected identities for read-only layers, filesystem roots, and pinned file children before processors run. Receipts report the objects actually opened. File children may follow their names or remain pinned, and a dormant filesystem slot may restore an aggregate.
Activation-record budget and encoding. The guide limits the opaque record to 1–1,024 bytes and lists its fields, but the host and guest libraries still need a canonical encoding and identity calculation. nvx-rs: replace activation RPC delivery with an uncaptured VMM configuration region #544 should confirm that the bound is sufficient on every backend.
State in the architecture guide the design that the image-backed runtime
roadmap needs, so that its differences from the guide can be reviewed
before implementation:
- a managed layered root with every control feature, readiness after root
assembly from boot tokens, and shared host and guest libraries;
- a distro image that is one EROFS filesystem or a GPT disk of ordered
layers;
- control protocol version 2 with standard input, per-execution credits,
and no total output limit;
- platform-clone inputs: zero-filled shorter layers, a RAM-layout platform
capture, an aggregate on a dormant filesystem slot, and an activation
record in restore packet version 5;
- a new network policy at restore for platform templates captured with a
deny-all policy;
- expected attachment identities, receipts, and pinned file children.
Section numbers, tables, figures, and anchors are unchanged.
Refs #535
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Make the guide changes consistent with the rest of the guide and tighten
their wording:
- run the boot conformance checks before a managed template's platform
capture, which precedes readiness;
- end platform-clone activation at readiness, so a host mapping failure
keeps refusing executions as after a cold boot;
- send the version-2 exit report after the last output of both streams;
- carry the workload-account request and the image's UUID or GUID in the
activation record;
- let hosts offer a new network policy only to clones of a managed layered
root, which learn their DNS server and ingress mode from the record;
- make scratch optional in restore reconstruction for the RAM-backed layout;
- complete Start once every announced mapping is mounted, and qualify the
failure summary for guest-validated activation records.
Refs #535
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Replace "embedding host adapters" with external orchestrators, which drive
the host control library through their own adapters, and describe an
external guest agent that runs as the guest's init process and embeds the
guest runtime library. The guide already uses "orchestrator" for the
software that drives NVX and "guest agents" for its guest software.
Refs #535
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The existing dormant-slot capability permits directory binding, but this wording also permits aggregate binding without a new platform-template capability. Sections 3.6.10 and 5.4.7 repeat that unrestricted permission. Linked #540 requires a newly versioned platform-template contract and preserves older/workload snapshot behavior; an old dormant slot does not establish that its guest supports aggregates. Require an explicitly recorded aggregate-binding capability on platform snapshots, and state the same restriction in all three sections.
Make credentials, account mode, machine identity, namespaces, mounts, and device visibility adapter-selected within library rules. Explain why listener announcements remain authentic while publication is active and align the surrounding guest-runtime text.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Keep private namespaces and the restricted device view specific to the layered root. Scope single-execution framing to NVXC, clarify adapter framing over NVXS, and tighten runtime identity, GPT, machine-ID, and execution-settlement details.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The RAM-backed overlay layout mounts its tmpfs upper at the kernel's default
size, half of guest memory, and adds no size token.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
The security-sensitive restore and isolation contracts need domain-owner review, particularly the unresolved activation-record encoding and size budget.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This updates the architecture guide with the target design for the shared image-backed sandbox runtime tracked by #535 and its current sub-issues. It defines the cold image-backed path and the common host and guest library contracts, and it also records the platform-clone design that will move to a separate platform-clone meta issue when that issue is filed. The guide describes the target rather than the current implementation. Refs #535.
Changes
distrois either EROFS or a primary-GPT image with opaque metadata in partition 1, which the adapter parses, and ordered read-only ext4 lowers in later partitions. Validation is bounded, expected identities are optional, kernel partitions must match validated entries, and the overlay uses one explicit option set with a safe choice for untrusted lower attributes. The RAM upper is selected by exactly onenvx_overlay_upper=ramfstoken: a tmpfs at the kernel's default size, with no scratch block.no_new_privsis mandatory. Layered-root executions move the root over/, receive private mount, PID, and UTS namespaces, and get restricted/devand/procviews. Listener-announcement authenticity now follows from the capability, sysctl, and read-only/proc/sysrules.READYreports the application version, build ID, root profile, and layered-root activation identity. Hosts validate it before mappings or execution. NVXC streams stdin, stdout, and stderr with separate bounded credits and no total output cap, defines bounded output draining and settlement, and runs one execution at a time. NVX adds a FIFO of eight waiters, a 60-second default wait, stable queue errors, and a non-escalating CLI Stop policy.getrandomafter reseeding; image machine IDs remain unchanged.Open points for review
Unchanged on purpose:
doc/run.mdanddoc/usage.mdcontinue to describe current CLI behavior. This PR changes only the target architecture guide.Validation
python scripts/check_markdown_links.pypasses.git diff --checkpasses for the full PR diff.