Repository navigation
Description
Parent: #1076. Phase: 3, NVX's own binaries on the new interface. Needs: #1081; inside phase 3, groups of #1083, #1085 (see the table below). Unblocks: inside phase 3, groups of #1083, #1085; #1086, #1090. The lanes of phase 3 meet at group level, never in a cycle: each group issue names the groups that it needs.
Goal. NVX's host can ask nvx-init for a capture and activate a restore over NVXC; a crate-private, cli-gated driver beside host::session drives a restore for blocking callers; and the CLI keeps named snapshots (#853), captures them, and restores sandboxes and one-off VMs from them (#837).
Today (dev e42b1795) and after:
| Area | Today | After |
|---|---|---|
| NVXC | No capture request or activate message. | A capture request, whose flag asks the guest to kill its executions first, and an activate message, which carries the activation record and nvx-init's workload setup, a restore's workload identity included; ControlSession::capture. |
| Restore driver | CloneControl. |
A crate-private blocking driver beside host::session, gated by cli, over RestoreMachine: it checks that the restore-ready client and the control server are the VM's process, sends the activate message on each session, and races every pending accept, read and write against its deadline, the caller's cancellation and the VM's verified exit. Its defaults are 60 s to Ready, 30 s to Start and 3 sessions. After Ready it sends the mapping table and Start, and returns the live session or a ControlRestoreError: the machine's error, or a MAPS or Start failure. |
| CLI | No snapshot command and no named snapshots; run --restore-snapshot passes a raw OpenVMM snapshot to OpenVMM. |
snapshot capture and snapshot restore; run --restore-snapshot restores from the CLI's strict snapshots. host::cli::snapshots keeps only named snapshots (#853), each published whole and kept immutable, and one exclusive lock per snapshot, which a restore holds from create through the peer-verified restore-ready event or the VM's verified exit; a restored sandbox's record names its snapshot. |
Groups, in order. Each group issue lists its PRs, with their goals, contents, Needs and estimates.
| Group issue | Delivers | PRs | Needs |
|---|---|---|---|
| #1113 | NVXC asks for a capture and activates a restore, and a blocking driver restores | SL4.2, SL4.3 | #1101, #1103 |
| #1114 | The CLI captures and restores named snapshots | SL3.7a, SL3.7b, SL3.8a, SL3.8b | #1102, #1108, #1109, #1110, #1113, #1117 |
Notes.
- The new messages land in
protocol::appas crate-private code, withexpect(dead_code)until nvx-init and the restore driver call them. nvx-rs slimming, phase 4.3: the code that only NVX's programs use, and the error codes, become private #1088 later makes the rest of NVXC private. - An interrupted capture isn't resumed. The capture VM is journaled like a sandbox's launch, so the next command's recovery ends its VM and removes its directory, and the user captures again. Once the capture VM exits,
snapshot::finish_capturechecks the capture and writeskey.binandsnapshot.jsonbesideopenvmm/in the capture VM's directory; the CLI then moves only those three entries into the named snapshot's private directory, keeps them immutable, and removes the capture VM's directory. - A restore whose command dies can't complete. OpenVMM checks the snapshot's files before it connects the restore-ready endpoint, once and without retry, so the CLI keeps no durable record of its restores; the next command's recovery ends the VM like an interrupted launch.
- A named snapshot is captured before a layered root exists. The Fresh capture VM's command line holds
nvx_sandbox=1and no root's tokens, so the shell/inithands it to nvx-init's capture entry, which assembles no root and waits for NVXC's capture request. - A raw OpenVMM snapshot is refused by
run --restore-snapshot, until snapshots of blockless VMs exist.
Tests. Round trips of the capture request and the activate message, and ControlSession::capture. The restore driver: its 60 s and 30 s budgets and its limit of 3 sessions; cancellation and the VM's exit during each I/O; a new session after one is lost; the refusal of a restore-ready client or a control server that isn't the VM's process; and distinct machine, MAPS and Start failures. The CLI: snapshot names, and a restored sandbox's record that names its snapshot; a capture that leaves exactly key.bin, snapshot.json and openvmm/ in its private, immutable snapshot directory and removes the capture VM's directory; an interrupted capture, whose VM the next command's recovery ends and removes; and a capture whose wait's deadline passes, which is stopped and never finished. Restores cover each image format and upper. Concurrent restores of one snapshot wait for each other's lock, and deprovision of a restored sandbox holds its snapshot's lock while it removes the view; a restore whose command dies is ended by the next command's recovery. run --restore-snapshot restores a strict snapshot and refuses a raw OpenVMM snapshot. Captures and restores on real VMs come in #1086.
Done when: every group issue is closed.
Activity
nvxa library of mechanisms and value types #1076[-]nvx-rs slimming, phase 3.2: snapshots through NVXC and nvx-cli[/-][+]nvx-rs slimming, phase 3.2: snapshots through NVXC and the CLI[/+]ppenna commentedon Nov 12, 2026
Completed. Both groups of this phase are closed:
Passing CI that contains all of them: the push run on
feature/nvx-refactorateb05744bd87, https://github.com/microsoft/nvx/actions/runs/43189211488.