Repository navigation
nvx-rs: the restricted control state and Activate after a restore, in the guest library and the test adapter's framing #843
Description
Parent: #834 (#833), step 3. Needs: #838, #842, and #822's PR 6 (Ready and the order, in the test adapter's framing); its VM tests run with #844. Unblocks: #844, #845.
Goal. After the repair acknowledgment, a clone's guest accepts exactly one Activate, on a restricted session. It validates the record before any side effect, activates its root and workload with the record's settings, and reports in Ready that the activation applied, with the transaction ID.
Today (dev d04d9fb):
- The guest attaches its control session with
nvx::guest::nvxs::GuestConnection::attach. It handles a host RESET,GuestEvent::Reset, by abandoning the old epoch and acknowledging with a receive window (nvx-rs/src/guest/nvxs.rs:134-180). At restore, OpenVMM queues a RESET for the session that the guest attached before capture. - The test adapter's host sends
RootConfig, and its guest answersRootReadyorRootFailed(tests/runtime-adapter/src/frame.rs:39-90,:152-193). runtime adapter: run cold sandboxes end to end on KVM, MSHV and WHP #822's PRs 4 and 6 add Ready, mapping tables and Start, in order. - Nothing restricts what a restored guest accepts.
Stacked PRs. Each PR builds on the one before it, and lands with its own tests.
PR 1 of 3: the activation state machine. Needs #838's PR 2 and #842's PR 2.
nvx::guest::clone::Activation, independent of any framing. Its states are transport bootstrap, restricted, activating, Ready with mappings pending, and started.- In the restricted state, the adapter passes it only NVXS bootstrap and flow control, and one Activate. Anything else is terminal.
- Activate is decoded and validated with
nvx::activationbefore any side effect, and its expected resources are checked against repair's result. - Retries: a retry with the same transaction ID and a byte-equal record joins the activation while it runs, and gets the cached result afterwards. A changed record, a new transaction, a later reset or a partial failure is terminal.
- Later sessions, such as after the host reattaches, get the established activation and transaction without activating again.
- The guest's activation deadline starts at its acknowledgment. Retries never extend it, and it stays live under trickled input and blocked output.
- Tests: the states, the deadline and retries; no request accepted before Activate; strict errors that never power off.
PR 2 of 3: root and workload activation. Needs PR 1.
- After a valid Activate, the guest activates the root and the workload as at a cold boot:
nvx::guest::root::assemblewith the record's settings and, if the record has a workload identity,Identity::new(uid, gid)in existing-account mode, with no supplementary groups or capabilities. Its account is checked in the assembled root before Ready, as NVX's init checks it at boot (guest/common/nvx-init-agent:620-645), and every execution runs as it. Without one, the adapter gives each execution its own identity, whichEntry::checkchecks. This PR covers EROFS images over tmpfs or a fresh scratch; nvx-rs: activate a clone's root for GPT images and either upper, with its export, network settings and workload view #845 adds GPT and the rest of root activation. - Ready's activation fields come from
nvx::activation::ReadyActivation: that the activation applied, and the record's transaction ID, beside the adapter's own identities. - Tests: fake backends that prove that no mount, spawn or ID generation happens before its gate; assembly and identity inputs taken exactly from the record; a workload identity without an account in the image, refused before Ready.
PR 3 of 3: Activate in the test adapter's framing. Needs PR 2, and #822's PR 6.
- The framing gets an
Activatemessage, and its Ready embedsReadyActivation's encoding (nvx-rs: a canonical activation record for platform clones #838):1, then the transaction ID. - The guest answers the RESET that the restore queued, and runs the state machine after repair.
- A record's workload identity becomes the clone's sandbox-wide identity, as a cold root configuration's is (runtime adapter: settle executions through cgroups and run them in a VM #805's PR 2): executions then name none.
- Tests: framing and session tests (
tests/runtime-adapter/tests/guest_session.rs). In VMs, with nvx-rs: restore clones from a template through Activate, Ready and Start #844's PR 5, on KVM, MSHV and WHP: no host input before the acknowledgment, and no workload before Ready.
Not in scope: NVXC v2's Activate frame (#851); the host's sequence (#844); GPT, the fresh-scratch check, the export, network settings, the hostname and the machine ID (#845).
Guide (#591's numbering): 4.4.2 (Ready's activation and transaction), 4.4.3 (the restricted session), 5.2.2 (the restore-ready event), 5.5.1 (the restore sequence), 5.5.9 (RPC Activate after the acknowledgment).
Done when: the three PRs are merged with their tests.
Activity
nvx-rs: activate a repaired clone through one Activate
nvx-rs: apply a clone's Activate to its root and workload
runtime-adapter: activate a clone through Activate in the framing
runtime-adapter: fail a clone on an Activate too long to read
nvx-rs: end a clone's application by its activation's deadline
nvx-rs: take a repaired clone's acknowledgement instant before its fi…
nvx-rs: poll for a clone's devices no longer than its deadline
runtime-adapter: take what a clone's session received before its Ready
nvx-rs: poll for a clone's devices at its deadline too
runtime-adapter: activate a clone through Activate in the framing
runtime-adapter: fail a clone on an Activate too long to read
nvx-rs: end a clone's application by its activation's deadline
nvx-rs: poll for a clone's devices no longer than its deadline
runtime-adapter: take what a clone's session received before its Ready
nvx-rs: poll for a clone's devices at its deadline too
nvx-rs: take a repaired clone's acknowledgement instant before its fi…
nvx-rs: activate a repaired clone through one Activate
nvx-rs: apply a clone's Activate to its root and workload