Skip to content

nvx-rs: give adapters the host mapping table, the rest of a launch's arguments, and the command-line count #929

Closed

Description

Goal. Adapters that embed nvx-rs through its public APIs keep their own copies of three things that NVX already implements, because NVX keeps them private or offers them only to its managed launches. Expose them, so that every adapter shares NVX's implementation and its tests.

Today (dev ce8c7d67):

  1. The guest's host mapping table.

    • The managed agent keeps the table's state in HostMappings: the count that the kernel command line announces, the mappings applied so far, whether a failure refused the rest, and the table's mapper and export (nvx-rs/src/guest/managed_agent/mappings.rs:25).
    • prepare reads the announcement and checks the export's mount (:113). apply_request checks each MAPS part against the table, applies its mappings in order beneath the table's root, and latches the table at the first entry that fails (:148). teardown unmounts the mappings in reverse order and reports each failure with its entry (:240).
    • All of it is crate-private, in a private module (nvx-rs/src/guest/managed_agent/mod.rs:93). An adapter's guest has nvx::guest::root::Root::map, nvx::guest::mappings and nvx::protocol::decode_guest_maps_payload, and keeps the table's state itself, as the test adapter's worker does (tests/runtime-adapter/src/worker.rs:33-84).
  2. The rest of an adapter's launch arguments.

    • LaunchSpec::openvmm_arguments renders OpenVMM's whole command line for a managed launch (nvx-rs/src/host/launch.rs:234).
    • For an adapter's launch, PreparedLaunch renders only the plan's options and the kernel command line (nvx-rs/src/host/sandbox/prepared.rs:281, :288). Each adapter adds the rest itself: --single-process, --hypervisor, --memory, --kernel, --initrd, --cmdline, --virtio-console, --microvm-control-console, --microvm-control-auth-stdin and --microvm-report, as the test adapter does (tests/runtime-adapter/src/layered.rs:284-330). A change to OpenVMM's options has to reach every copy.
  3. The process command-line count.

    • process_command_line_units counts the Windows command line that runs a program with its arguments, as Windows quotes it (nvx-rs/src/host/launch.rs:372), and is private. fit_process_command_line is crate-private (:284), and so is its reserve (:28). LaunchSpec::check_process_command_line (:277) checks a managed launch only.
    • Nothing checks an adapter's launch against PROCESS_COMMAND_LINE_LIMIT (:25), so a plan with many mapped paths or network rules can render a command line that Windows refuses when it creates the VMM. An adapter that checks it counts again, with its own copy of the quoting rules.

Proposal:

  1. A public guest-side type for the host mapping table, with the managed agent's behavior: read the announcement, check and apply each part in order, latch a failure with the entry that failed, and tear the table down, beneath a root of the caller's choice. The managed agent uses it too.
  2. A public renderer of an adapter launch's complete OpenVMM arguments, from its PreparedLaunch and the launch's own inputs: the hypervisor, memory, kernel, initramfs, endpoints and report. LaunchSpec can share it.
  3. A public count of a program and its arguments as Windows quotes them, and a check of an adapter's launch against PROCESS_COMMAND_LINE_LIMIT, with a documented reserve, so that planning can refuse a plan whose options leave the rest of the launch too little.

Downstream. Move the test adapter onto these. Once they are released, make sure that downstream users are updated to use them in place of their own copies.

Not in scope: the MAPS wire format, the managed launch's arguments, and the limit itself.

Activity

  1. ppenna commented on Nov 1, 2026

    @ppenna
    Contributor

    #1071 delivered this issue's NVX work, which dev has had since its merge commit 764b2da on October 31. The one task that #1071 left open, moving downstream adapters onto these APIs once a release includes them, is left to the downstream repositories, so I'm closing this issue as completed.

    What dev has (checked at e92bfb5):

    1. The host mapping table: nvx::guest::mappings::MappingTable, with TableError and Refusal, which the managed agent also uses (cd7c340). As nvx-rs: give adapters the host mapping table, the rest of a launch's arguments, and the command-line count #1071's design notes explain, the root that applied the mappings tears them down (Mapper::teardown, Root::teardown), not the table.
    2. The rest of a launch's arguments: VmmLaunch, which LaunchSpec::openvmm_arguments shares, and PreparedLaunch::adapter_arguments (17905e9).
    3. The command-line count: the public process_command_line_units and fit_process_command_line (e568670), and SandboxPlan::check_adapter_launch with the documented VmmLaunch::RESERVE of 2,048 UTF-16 code units (51b354a).
    4. The test adapter uses all three and keeps no copies. Its worker keeps the table in MappingTable (af481bd). Its layered launch renders through adapter_arguments and checks its plan with check_adapter_launch (f50f626).

    CI run 41161285842 passed for #1071's head, f50f626.

    Release. No release on crates.io has these APIs yet:

    Downstream. crates.io lists two crates that depend on nvx, aci_edge_sandboxes and aci_edge_sandboxes_model 0.1.0 from Azure/aci-edge-sandbox, both pinned to nvx =0.1.0-alpha.6. At Azure/aci-edge-sandbox@08708d1, their sources re-export nvx but use only resolve_guest_path, the error types, Hypervisor, and net from it. They keep no copy of the table, the launch arguments, or the count. The agent library that their bundle ships, which drives OpenVMM, is not part of that repository's sources. GitHub code search for decode_guest_maps_payload, --microvm-control-auth-stdin, and PROCESS_COMMAND_LINE_LIMIT found no other users outside NVX and its forks. The downstream repositories own the move onto these APIs, which can start once 0.1.0-alpha.9 is published.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions