[Enrique Saurez (esaurez)]

Chain: #951 → #954 → #957 → #959 → #960 → #955 → this PR, on dev; #879, #881, #885, #886, #877, #932, #884, #887, #933, #880, #936, #937, #939, #940, #941, #888, #949, and #950 have merged.

Stacked on #955. Part of #846 (PR 2 of 2: network templates). It builds on PR 1 (#955), and on the network settings that #845's PR 3 (#960) gives a clone.

One template per network policy

A template's NIC is restored with the network that its capture attached, so a template can serve only the clones of that network. Before this change, a clone's plan checked only that the template had a NIC when the clone's plan had a network, at the guest address and prefix of that NIC, and the restore passed the policy of the clone's own network. OpenVMM then refused another policy at the restore, after the VMM started.

The template key now holds the network as the capture class lowered it to OpenVMM's arguments, SandboxNetwork::openvmm_arguments: --net with the guest's address and prefix, then the options of the policy. A template without a NIC holds none, and so does a network that lets nothing through, which attaches no NIC either: they share the no-network identity. NVX already has that lowering, so the key holds no new digest, and nothing is hashed.

• ClonePlan::new lowers the network of the adapter's plan and compares it with the key's. It refuses, before any VMM starts, a network for a template without a NIC, none for a template with one, and another policy or guest address. Each is a failure of the request, Evidence::InvalidSettings. This one comparison replaces the check of the guest's address that nvx-rs: attribute a clone's failures, record them, and reattach it #951 made, and keeps that check's message for another address or prefix.
• ClonePlan::launch passes the key's network unchanged, but --net and the address, which OpenVMM takes from the snapshot and refuses beside it. The clone's own plan no longer adds a network to the restore, so the restore has no --net of the plan's to drop.
• No clone gets ingress, host-loopback access to its listeners, or forwards: a template's capture refuses a policy that allows ingress or two-way host-loopback access, which forwards need. Listener publication stays with nvx-rs: per-clone network policies on deny-all templates #850.

The key's network

The key's canonical encoding takes the network as its eighth part, a list of texts, and stays version 1. TemplateKey::from_bytes checks that the list is exactly the arguments to which a network of a guest at the NIC's address lowers: it reads the policy back from them, as nvx-rs sandbox reads its network options, and lowers it again with the NIC attached, network::attached_arguments, since a closed policy whose allow rules lower to no OpenVMM rule still attaches its NIC. For a machine without a NIC, the list is empty. A key whose network no policy lowers to is malformed, which ClonePlan::new attributes to the generation, rather than accepted with a network that every clone's plan mismatches. The check is CPU work alone, with no I/O or hashing.

• The key's encoding has not been released, so a template store that an earlier build created is not supported: delete it and create a new one. There is no migration, and no compatibility code: the key's version, the capture class, and the template store's record format, STORE_FORMAT, stay as they were. Every key ends with its network, an empty list for a template without a NIC, so bytes without it are refused as malformed, the generation's failure, Evidence::MalformedGeneration, and never read as the key of a template without a NIC. A key of another version stays the host's, Evidence::IncompatibleHost, which quarantines nothing.
• The key's vectors in nvx-rs/tests/vectors/template-key-v1.txt change in place, generated from the definition, which nvx-rs/tests/vectors/README.md records as the second exception to its rule that a vector changes only with a version. The capture class's encoding and vectors are unchanged.

Starting a clone of a network template

runtime-adapter-host start takes a launch's --network FILE, which it reads before anything else, as a launch does, and refuses with status 1 if it cannot read it or the plan refuses it. clone::Request carries the network, and Request::plan puts it on the adapter's plan, which NVX's plan compares with the template's.

The clone's record keeps the plan, with its network, so exec gives a clone's executions the URL of the network's proxy in http_proxy, https_proxy, HTTP_PROXY, and HTTPS_PROXY, as for a launch. It is the URL that the clone's activation record names, since both come from the same plan.

Tests

• Key: the network that a class lowered, round-tripped, for every form of policy (rules of both families, outbound and two-way host-loopback access with forwards, a proxy, and a closed policy whose allow rule excepts its whole destination, with and without deny rules); a closed network, which has the no-network identity; a key that changes with an egress rule or default; and the refusals of a network without a NIC, a NIC without a network, a network at another address, networks that no policy lowers to (the address alone, options out of order, another profile, a rule that OpenVMM would not read or that a lowering writes in another form, an option without its value, an unknown option, the address twice, and a proxy beside allowed egress), a key without its network, and keys of other versions. The vectors cover each refusal. network::attached_arguments renders the closed policy's device as one more allow rule that lowers to no OpenVMM rule does, and any other policy as openvmm_arguments does.
• Clone planning and launch, with a fake VMM: against a template with a NIC, another guest address and another prefix, refused with the message of nvx-rs: attribute a clone's failures, record them, and reattach it #951's check, and three other policies at the template's address; a network refused against a template without one; and the restore's arguments, which are the key's.
• Test adapter: start --network refused when given twice; a network that cannot be read, or that the plan refuses, refused before the image, the shares, and the template store; and a request with a proxy-only network, whose plan, NVX request, and record carry the network, so that an execution finds the proxy's URL.
• VM tests (vm_clone), on KVM, MSHV, and WHP:
  • A template without a NIC serves clones without a network and of a network that lets nothing through: no network device, no network in the record, and the image's own /etc/resolv.conf, which no bind holds. A clone of each network with a NIC is refused before any VMM starts.
  • A template of each network with a NIC that a capture takes (egress allowed, with or without outbound host-loopback access, an allow rule, and a proxy) serves a clone of its own network. The clone has one network device, on Linux the VMM's arguments of the template's policy without --net, and a record that names the policy, the gateway's DNS server where egress is allowed, and the proxy. Its restored NIC lets through what the policy allows alone: the tests bind three listeners on host loopback, the proxy's, the allow rule's, and one that no network names, at ports that the host chooses, and an execution's TCP connection to the gateway at each port opens, and arrives at the listener, where the policy lets it through, and fails, with nothing arriving, elsewhere. The allow rule's clone reaches its listener alone, the proxy-only clone the proxy alone, the clone with egress and outbound host-loopback access all three, and the clone with egress allowed alone none. Each other network, the same policy at another guest address, a closed network, and no network are refused before any VMM starts. The templates' policies differ.
  • DNS: with egress allowed, /etc/resolv.conf is a file of mode 0444 that names the gateway's DNS server, held by a read-only, nosuid, nodev bind after that of a generated machine ID, which mount tables list. A write as root cannot change it. A TCP connection to the server's DNS port opens, which the gateway's DNS proxy accepts itself, so the check does not depend on the host's resolver or its upstream servers.
  • Status 57: a clone of a disk whose layer holds a regular file etc ends before it is ready, by the evidence of invalid settings.
  • Proxy: the executions of a clone of a proxy-only network find the proxy's URL after their own entries, and one that names its own proxy settings keeps them.
  • A clone of a template with a NIC maps its export below the binds of its machine ID and its resolver configuration.

The scenarios of exports from PR 1 keep templates without a NIC, so their mount tables hold no resolver configuration.

Validation

At this PR's head e19ceed, the commits of the earlier head e9e7fc6 are rebased unchanged onto #955's head 551ebda. Its tree, 21eab61f, is the merge of e9e7fc6 into dev at fbeb563, which holds #951, #954 and #957, on top of #960's head efe51b4. It adds #955's fix from a review thread, which makes ExportPlan::verify report a path whose links loop as a changed object. CI at this head, in run 40901423035: 36 jobs passed, among them the microVM tests and the platform checks on KVM, MSHV and WHP, and OpenVMM's unit and VM tests; the six that run only for a pull request or on dev were skipped. CI at the head before #955's fix, 2a777a3, whose tree, acbf8180, is that merge alone, in run 40896659416, passed the same way. A pre-check of acbf8180 passed on Linux and on Windows: the library's documentation with -D warnings; the test adapter's documentation in its protocol-only and host configurations, and in its musl guest configuration on Linux; validate-nvx; and the Markdown links. At this head, for #955's fix, on Windows: fmt; Clippy with -D warnings of all targets with all features, and of all targets with all features for x86_64-unknown-linux-musl; and the tests of host::filesystem and tests/host_modules.rs. On Linux x86_64: Clippy of all targets with all features, the tests of host::filesystem, and the aarch64-apple-darwin check. The rest of this section describes the validation at e9e7fc6, on #955's earlier head 08d111c.

At the final restack, onto #955's head with OpenVMM 832d5bb4, each commit on its own:

• Windows: nvx-rs's fmt; Clippy with -D warnings of all targets with all features, of the library with the default features and without them, and of all targets with all features for x86_64-unknown-linux-musl; tests/host_modules.rs; and the library tests of host::template, host::filesystem, host::network, and protocol. The test adapter's fmt; Clippy of its protocol-only, host, and x86_64-unknown-linux-musl guest configurations; and its protocol-only, host library, host_session, and clone_start tests. The check of the README's module table in scripts/test_nvx_tools.py.
• Linux: the macOS check; the guest::mappings and guest::managed_agent tests, as the user and as root with the root-only tests; and the test adapter's guest library and guest_session tests for x86_64-unknown-linux-musl.
• At this head, also: the docs with -D warnings, MSRV 1.89 of nvx-rs and of the test adapter's three configurations, and the Markdown link check.

At this head:

• The CI workflow: every job passed, the VM tests on KVM, MSHV, and WHP included, where the test adapter's vm_clone passed 25 of 25, the export and network scenarios included, and vm_template 9, vm_layered 43, vm_restart 3, and vm_steps 3.
• Windows: the nvx-rs checks (fmt; Clippy of all targets with all features, of the library with the default features, and of the library without them; tests with all features, the defaults, and without default features; docs; MSRV 1.89), Clippy of its guest code for x86_64-unknown-linux-musl, tests/host_modules.rs, the test adapter's protocol-only and host checks and Clippy of its guest, the check of the README's module table, scripts/nvx.py verify, and the Markdown link check.
• Linux: the same nvx-rs checks, its macOS check, and Clippy of its guest code for x86_64-unknown-linux-musl; the lint and the tests of the guest binaries (scripts/nvx.py check-guest-binaries); the test adapter's protocol-only, host, and guest configurations, each with its Clippy, build, tests, and MSRV; and, as root, the tests that need it (198 of 198, the 13 that only root runs included).
• On MSHV and WHP, with the OpenVMM of the development release v0.1.0-dev.2d14547b669f, which nvx-rs download installed, and the initramfs and the test adapter's guest agent built from the tree: vm_clone 25 of 25, vm_template 9, vm_layered 43, vm_restart 3, and vm_steps 3.

These runs hold for this head, e9e7fc6, by tree identity: the CI workflow ran at cfdc779, and the Windows, Linux, and VM runs at 954d098, before this branch's fix-ups were squashed into its second commit, which changed no file. cfdc779 has this head's tree, 72dea16c, and 954d098's tree differs from it in a comment alone.

[Copilot]

🟡 Changes recommended

Obsolete version-1 keys can block template startup and recovery after upgrades, while malformed network arguments can be accepted instead of quarantined.

3 open issues

• Skip or quarantine obsolete generations during selection · New
• Recover interrupted captures with obsolete keys · New
• Validate complete network arguments before accepting keys · New

What changed in this PR

Implements policy-specific network templates for NVX clones as the second part of #846, building on the export support in #955/#956 and network activation settings from #845.

Changes:

• Adds network arguments to version-2 template keys, rejects mismatched clone networks before launch, and restores the template’s policy.
• Adds start --network support to the runtime adapter and preserves proxy settings for clone executions.
• Expands key, planning, CLI, and VM tests for network compatibility, DNS, proxies, and exports alongside resolver mounts.

File	Description
tests/​runtime-adapter/​tests/​vm_clone.rs	Adds network-clone VM scenarios.
tests/​runtime-adapter/​tests/​clone_start.rs	Tests network options, early rejection, and proxy persistence.
tests/​runtime-adapter/​src/​clone.rs	Carries network settings through clone requests and plans.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-host.rs	Accepts and reads start --network.
tests/​runtime-adapter/​README.md	Documents network clones and their test scenarios.
nvx-rs/​tests/​vectors/​README.md	Documents version-2 key vectors.
nvx-rs/​src/​host/​template/​store/​tests.rs	Tests rejection of version-1 keys.
nvx-rs/​src/​host/​template/​mod.rs	Updates template compatibility documentation.
nvx-rs/​src/​host/​template/​key/​tests.rs	Tests network identities, decoding, and version-2 conformance.
nvx-rs/​src/​host/​template/​key.rs	Encodes network arguments in version-2 keys.
nvx-rs/​src/​host/​template/​clone/​tests/​launch.rs	Checks restore arguments against the template’s network.
nvx-rs/​src/​host/​template/​clone/​tests.rs	Tests policy mismatches and obsolete-key failures.
nvx-rs/​src/​host/​template/​clone/​launch.rs	Uses the template’s network arguments during restore.
nvx-rs/​src/​host/​template/​clone.rs	Enforces network compatibility before launch.
nvx-rs/​README.md	Updates library documentation for policy-specific templates.

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The version bump can strand existing templates and block store recovery, while fully excluded network allow rules can produce keys that fail round-trip validation.

3 open issues

• Handle fully excluded allow rules during validation · New
• Recover interrupted captures with obsolete keys
• Skip or quarantine obsolete generations during selection

1 resolved since last review

• Validate complete network arguments before accepting keys

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The clone tests do not verify post-restore traffic enforcement for allow-rule and proxy-only policies, leaving policy enforcement regressions undetected.

1 open issue

• Add traffic enforcement tests for cloned allow-rule and proxy-only policies · New

3 resolved since last review

• Handle fully excluded allow rules during validation
• Recover interrupted captures with obsolete keys
• Skip or quarantine obsolete generations during selection

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

The current OpenVMM pin lacks the required export fix, and the restacked head still needs VM validation across KVM, MSHV, and WHP.

No open issues 🎉

1 resolved since last review

• Add traffic enforcement tests for cloned allow-rule and proxy-only policies

_{Review effort: Balanced}

[Copilot]

🟡 Changes recommended

The DNS test depends on the host’s upstream resolver, so a slow or unreachable upstream can cause a timeout and falsely fail the restored-network test.

1 open issue

• Avoid host DNS dependency in invalid-domain timeout test · New

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Human assessment is needed because a no-traffic network can still attach a NIC in an excluded-destination edge case, contrary to the documented behavior.

No open issues 🎉

1 resolved since last review

• Avoid host DNS dependency in invalid-domain timeout test

_{Review effort: Balanced}

[Copilot]

🔵 Needs a closer look

Backend-dependent network isolation and restore behavior still need exact-head VM and CI validation across KVM, MSHV, and WHP.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No active review issues remain for the network-template clone changes.

No open issues 🎉

_{Review effort: Balanced}