Repository navigation
NVX host/guest library wiring workstream: move NVX's binaries and tools onto the shared host and guest libraries #816
Description
Objective. #535 built the shared host and guest libraries in nvx-rs and proved them through the in-repo test adapter (tests/runtime-adapter), which embeds them through public APIs only. NVX's own binaries and tools still keep parts of their earlier implementations. This issue moves them onto the shared libraries, so that NVX keeps one implementation of each mechanism, and then proves both adapters end to end on KVM, MSHV and WHP.
It holds the work that #535 left: NVX's Rust layered init, the CLI's image formats and protected paths, the exec protocol cutover with its admission and build identity, the test adapter's end-to-end runs, and the final acceptance. The libraries' interfaces stay as #535 delivered them; each child lists any addition it makes: #822 an export mount for mapping tables, and #860 a resolver bind and removable runtime binds.
Today (dev c5a0dd7) and after:
| Component | Today | After | Issue |
|---|---|---|---|
| Layered root in the guest | The shell init (guest/common/nvx-init-agent) bootstraps, assembles and tears down the root: one EROFS distro over an ext4 scratch. It refuses GPT and the RAM upper. A one-shot sandbox enters its workload through the shell helpers (nvx-container-launch, nvx-container-enter); managed executions already enter through nvx::guest::entry |
NVX's Rust PID 1 runs the root through nvx::guest::root and nvx::guest::entry, for managed and one-shot execution, in all four format and upper combinations |
#817 |
| CLI images and shares | nvx-rs sandbox takes --layer ROLE,PATH,EROFS_UUID only, and refuses shares only when they overlap each other. nvx-rs run, which boots a plain VM, renders its shares itself (extend_shares_and_network) |
sandbox run, provision and start take EROFS or GPT over scratch or tmpfs, and refuse a share that reaches the state directory, scratch, layers or bundle. nvx-rs run plans its shares with filesystem::plan |
#818, #802 |
| Exec protocol | NVXC v1 and FEATURES. The host and the guest still parse EXEC's body separately; MAPS entries and EXEC's fixed header are shared. The guest gives workloads stdin from /dev/null, kills one whose output passes 1 MiB, and answers BUSY to every request during an exec, Stop included. The CLI collects output in memory |
NVXC v2 over NVXS, driven by nvx::exec: stdin, stdout and stderr stream under credit, with no total output cap. A typed Ready is validated before MAPS and EXEC. v1 and FEATURES are removed |
#581, #821 |
| Admission | OpenVMM's broker admits one host at a time; nothing queues CLI processes | A FIFO across CLI processes: one active exec, at most 8 waiters, a 60 s default wait, and a Stop that bypasses it | #819 |
| Guest identity and packaging | No guest build identity. bundled stages v0.1.0-dev.9ceb89fcc31f, whose guest still has the C agent |
A build ID from canonical build inputs, bound to the initramfs and reported in Ready. bundled serves the final matched release |
#820, #624 |
| Test adapter | Its VMs assemble all four format and upper combinations outside PID 1 on every backend, but run no execution in a VM, attach no network, and pass their own launch arguments rather than a checked handoff | Real cold launches with executions, mappings and network policy, through the adapter plan and the checked handoff; its consumer-contract scenarios on real VMs | #822, with #805; #859 |
| DNS in a layered root | /init writes the initramfs's resolver; a layered root's workloads see the image's own /etc/resolv.conf, empty in NVX's images |
The runtime binds the guest's resolver over the root's /etc/resolv.conf when the policy allows DNS, for cold boots and clones |
#860 |
| Windows checked handoff | A launcher that ends before OpenVMM opens the images releases their guards | The guards last until OpenVMM has opened the images | #780 |
| Tests and evidence | #601's direct-mode cases are unported. No coverage manifest | #601's cases run without privileges. The conformance matrix runs with both adapters, with durable evidence | #601, #624 |
Children and order. Most children can start now. The table lists the real dependencies; each child's tests land with it.
| Issue | Scope | Needs |
|---|---|---|
| #817 | NVX's Rust layered init for managed and one-shot execution | #822's PR 5 (the export mount); #860's PR 1 (the resolver) |
| #818 | GPT images, the RAM upper and protected paths in nvx-rs sandbox |
#817 to boot GPT and tmpfs |
| #802 | nvx-rs run's shares through the export planner |
— |
| #581 | One EXEC body decoder for the host and the guest | — |
| #819 | The CLI's exec admission across processes | — |
| #820 | Guest build identity and packaging | — |
| #821 | NVXC v2 and a validated Ready | #581 and #820; #817 for the layered root's activation identity |
| #822 | The test adapter end to end, in eleven stacked PRs; #805 runs its executions in VMs | — |
| #859 | The test adapter's consumer-contract scenarios C2, C3, C6 and C7 on real VMs | #822 and #805 |
| #860 | DNS inside a layered root, for cold boots and clones, and runtime binds that a teardown can remove | — for its library PR; #822 for the test adapter's |
| #861 | Whether adapters' layered launches need OpenVMM's workload lifecycle | — |
| #601 | The managed agent's direct-mode tests without privileges | — |
| #780 | Windows: checked images stay guarded until OpenVMM opens them | — |
| #624 | Final acceptance, the coverage manifest and the bundled re-pin |
All of the above; #782 for the released-artifact lane |
Consumer-contract suite. Both adapters run #535's scenarios C0–C8. #535's phases added the library-side tests; the children above add NVX's adapter and the test adapter's remaining cases, and #624 runs the full suite.
Not in scope:
- changes to the libraries' interfaces beyond the additions that a child lists;
- the blockless root's init, which keeps the shell, and other PID 1 profiles;
- platform clones, the snapshot/restore workstream (Snapshot/restore workstream: start sandboxes from captured templates through the shared host and guest libraries #833), and performance measurements and budgets, the performance workstream;
- exec concurrency in NVX's adapter, TTY and arbitrary signals;
- image slots, device hotplug and capability discovery.
Acceptance. #624's: both adapters run the shared host and guest code end to end on KVM, MSHV and WHP, with exact provenance, the zero-read check with its positive control, recorded sizes, and bundled serving the final matched release.
Related:
- sandbox: bind GPT disks, plan adapter launches, and stage registered images #813 (GPT bindings, the adapter plan, and registered images in
aci_edge_sandboxes) completed Shared image-backed sandbox runtime #535's library changes; nvx-rs: GPT images, the RAM upper and protected paths innvx-rs sandbox#818 and runtime adapter: run cold sandboxes end to end on KVM, MSHV and WHP #822 build on it. - nvx-rs: run NVX's layered sandbox root from a Rust PID 1 on the guest library #817 and nvx-rs: GPT images, the RAM upper and protected paths in
nvx-rs sandbox#818 deliver Overlay upper: support virtio-blk scratch or tmpfs end to end, and align docs #558 (either upper, end to end), with doc: describe the managed layered root and platform-clone activation #591's docs. nvx-rs: check a GPT disk's kernel partitions in the guest #770 isn't needed: platform clones reread the partition table before the existing checks (nvx-rs: activate a clone's root for GPT images and either upper, with its export, network settings and workload view #845). - The snapshot/restore workstream (Snapshot/restore workstream: start sandboxes from captured templates through the shared host and guest libraries #833) starts from Shared image-backed sandbox runtime #535's libraries now. Its stage 1 needs, first, the PRs of runtime adapter: run cold sandboxes end to end on KVM, MSHV and WHP #822 and runtime adapter: settle executions through cgroups and run them in a VM #805 that Snapshot/restore workstream, stage 1: templates and clones in the shared libraries, on today's OpenVMM #834 lists, and nvx-rs: give a layered root's workloads the DNS server that their network policy allows #860's PR 1. nvx-rs: move NVX's adapter to NVXC v2 on the shared engine, with a validated Ready #821 reuses nvx-rs: a canonical activation record for platform clones #838's activation-configuration identity. NVX's template mode needs nvx-rs: run NVX's layered sandbox root from a Rust PID 1 on the guest library #817, its Activate frame needs nvx-rs: move NVX's adapter to NVXC v2 on the shared engine, with a validated Ready #821, and its acceptance extends nvx-rs: final acceptance for the image-backed runtime #624's harness.
- Tracked separately: nvx-rs: the golden CLI scenarios fail when the tests run as root #739 (golden scenarios as root), nvx-rs: retire the Python-parity golden tests and make Rust the reference #722 and nvx-rs: replace the golden CLI scenarios with structured scenario tests #728 (retiring the golden scenarios), nvx-rs: turn the wire-format golden bytes into versioned conformance vectors #727 (conformance vectors; v2 gets its own in nvx-rs: move NVX's adapter to NVXC v2 on the shared engine, with a validated Ready #821), and microVM: reconcile the 64-KiB command-line limit with the guest kernel's limit #570 (the guide's command-line limit, in doc: describe the managed layered root and platform-clone activation #591).
Activity
nvx-rs sandbox#818runthrough the export planner #802nvx-rs sandbox execthrough a bounded queue across CLI processes #819[-]Move NVX's binaries and tools onto the shared host and guest libraries[/-][+]NVX host/guest library wiring workstream: move NVX's binaries and tools onto the shared host and guest libraries[/+]