GeezerVison

Copilot AI left a comment

The external-launch example handed the command that vm::create prepares
to host::supervisor::spawn_vm, the strict low-level spawn that SL6.1
left public only as a transitional path. SL6.3 deletes that path, and
as SL2.8b designed it, the caller of vm::create supplies its own spawn:
the library keeps no public low-level spawn besides vm::spawn.

The example now starts the VMM with a minimal launcher of its own, on
std::process: it writes the capability into a pipe that it closes to
writers before the spawn, gives the VMM that pipe as its standard input
and the log as its standard output and error, holds the process through
a ProcessRef and Process::open, and kills and reaps it if anything fails
once it runs. It reads the ProcessRef's start time itself, as ProcessRef
defines it: the starttime field of /proc/<pid>/stat on Linux, and the
process's creation time on Windows. So it uses nothing of
host::platform, which SL6.14 makes crate-private, and takes Transport
from host::transport, which re-exports it. Its docs list what it leaves
out of the launch contract of vm::VmmCommand, which a production
launcher adds, as vm::spawn does: it passes no descriptor or handle
besides the standard streams, and refuses a command that allows any; on
Linux it starts the VMM in a process group of its own, but not in a new
session, and leaves the caller's umask; on Windows it starts the VMM
without a console, but with every inheritable handle of the caller and
in no log-named job.

The README's description of the example, and its row in the case
matrix, which stays kept, say so.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

A PreparedLaunch handed OpenVMM the files that the checks of a plan's
images opened: /proc/self/fd/N on Linux, which the VMM inherited through
the supervisor's allowlist, and on Windows the checked files' final
paths, which their handles held, and which PreparedLaunch::release
closed in the VMM through ProcessHandle::close_inherited. No launch
uses it any more: the CLI's start and run name their images by path in
the VM's configuration, and pass the VMM only the scratch image's claim,
through Prepared::inherit.

So the prepared launch goes: host::sandbox::prepared and PreparedLaunch,
with PreparedLaunch::adapter_arguments, and the checked-file handoff
that only it used: Inherited::proc_path and the crate-private
Process::close_inherited and ProcessHandle::close_inherited of Windows.
The crate-private code that only they used goes too:
move_above_standard_streams on Linux, seal::final_path on Windows, and
the file_mut of CheckedDistro and CheckedScratch, and CheckedDistro's
bound(), whose identity field then went unread. CheckedScratch::claim,
which only the CLI reads now, as it hands the claim to the VMM, is gated
by cli, and the claim's field, which holds the claim whoever reads it,
is allowed to go unread without cli.

The docs say what stays: a launch names its images by path, so what
takes an image's path after its check is what OpenVMM opens, and callers
stage their images in a directory that only their own account can
write, as the docs of distro, scratch and seal require, so that no other
account can replace a checked image. The README's "Checked handoff"
section becomes "Images by path", and the claims of the scratch image
no longer say that the VMM opens /proc/self/fd/N or that a release
closes its copies.

Tests: the handoff's cases retire with it: the 4 cases of
tests/checked_handoff.rs that hand a prepared launch's images to a VMM
fixture, with their launcher fixture and helpers; the 10 unit tests of
host::sandbox::prepared; the Windows platform's
a_child_loses_only_the_inherited_handle_that_is_closed_in_it, the test
of close_inherited; and seal's final_paths_hold_no_nul_whatever_their
_length, the test of final_path. checked_handoff.rs keeps its 2 cases
of the spawn that stays, a wait's exit status and the strict cleanup,
which SL6.3 moves to their owner with the supervisor. The test of the
spawn's allowed descriptors no longer checks proc_path, and the test of
a GPT binding's check no longer checks bound(). The case matrix retires
the doc test of PreparedLaunch and the adapter's scenario
images_replaced_after_the_checks_never_reach_the_vm, and stops naming
the deleted handoff test as coverage of
a_layered_launch_hands_openvmm_the_checked_images.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

`host::supervisor` re-exported the low-level spawn of a VMM, `spawn`,
`spawn_vm`, `VmmCommand`, `Launched` and `Inherited`, and
`spawn_command`, for the code that still used them after SL6.1: the
`external-launch` example, which now launches its VMM with a launcher
of its own, and the tests of the spawn in `tests/supervisor.rs` and
`tests/checked_handoff.rs`. `host::vm` spawns VMMs.

The module goes, with what only it made public or used:

- `spawn`, the spawn without the strict log job, `spawn_vm`, its strict
  twin, and `VmmCommand::new`. `vm::spawn` keeps the strict spawn,
  `spawn_vm_with_mode`, which takes their documentation, and builds its
  command whole.
- `Launched::kill_and_wait`, the legacy time-bounded cleanup, with the
  Windows `LaunchedProcess::terminate` that only it called.
  `kill_and_confirm_exit` stays.
- `spawn_command`, which spawned a `std::process::Command` under the
  crate's spawn lock. The tests spawn theirs with `spawn_locked`.

`VmmCommand`, `Launched` and `Inherited` become crate-private. What
only the CLI's one-shot runs use outside the tests,
`Launched::wait_timeout` with its reaping and status helpers, the
Windows `LaunchedProcess::wait_timeout`, and `KILL_TIMEOUT`, carries an
`allow(dead_code)` for builds without the `cli` feature, as do the
spawn lock outside Windows, which only the tests take there, and
`VmmCommand::breakaway_from_job`, which only Windows reads.

Tests move to the owners of the code that they test:

- `tests/supervisor.rs` becomes `tests/process.rs`, with its seven tests
  of `nvx::host::process`, whose processes a fixture of its own starts
  through `std::process` now: `processes_can_be_shared_between_threads`,
  `a_child_that_exits_wakes_its_waiter`,
  `a_process_that_is_not_a_child_wakes_its_waiters`,
  `a_reused_process_id_is_never_signaled`,
  `references_that_name_no_process_are_never_opened`, and on Windows
  `a_process_that_this_user_may_not_query_has_an_unknown_state` and
  `a_process_that_this_user_may_not_terminate_is_waited_for_but_never_signaled`.
- Its four tests of the spawn,
  `working_directory_limits_include_trailing_separators` (Windows),
  `a_restarted_launcher_finds_its_vmm_again_and_ends_it`,
  `vmms_inherit_only_their_streams_and_allowed_descriptors_while_others_spawn`
  and `a_job_that_ends_its_vmm_wakes_the_waiters` (Windows), and the two
  of `tests/checked_handoff.rs`,
  `launched_waits_return_and_retain_the_actual_exit_status` and
  `strict_cleanup_terminates_and_confirms_a_running_child`, move to the
  spawn's unit tests, `src/host/spawn/tests.rs`, which now build on
  Linux and Windows, with one VMM fixture for the two files' fixtures,
  and the launcher fixture. The spawn's Linux tests move to
  `src/host/spawn/tests/linux.rs`, unchanged but for the strict spawn.
- In the unit tests, which run beside hundreds of others, the check that
  a process that `std::process` spawns while VMMs spawn holds none of
  their descriptors looks again until the objects are gone or a second
  passes. The kernel wakes `posix_spawn`'s parent before the child's exec
  closes its close-on-exec descriptors, so for an instant the child's
  table still lists every descriptor of the parent, which the busier
  process made the check see as a leak.
- The tests that spawned through the old paths spawn through
  `spawn_vm_with_mode`, and end their children with
  `kill_and_confirm_exit` or `terminate_and_wait`. The Windows test of a
  log that is no file of a disk volume keeps its refusal by the strict
  spawn and loses the start without a job that only `spawn` made, as
  `a_vmm_whose_log_is_no_file_of_a_disk_volume_is_refused`.
  `the_graph_holds_well_known_dependencies_of_the_sources` loses the
  edge from `supervisor` to `spawn`.

Docs: the README loses the module's row and section; the
`nvx::host::vm` section takes its notes on the umask and the
working-directory limit, and names the spawn's tests. The case matrix's
row of the module's doc test says where its tests went. The public-API
snapshots lose the module.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

`CaptureClass`, the invariant inputs of a template's capture that an
adapter requested, with its canonical encoding and `ClassIdentity`, and
`SnapshotKey::new`, which derived a key from a class and its capture's
manifest, served only the old capture path and the tests. A capture's
key comes from its `CaptureContext`, which `vm::create` prepares and
`finish_capture` reads, through `SnapshotKey::from_capture`.

The class goes, with its identity and its domain, and the import of
`PROCESSOR_COUNTS` that only its check used. The docs of the key, of its
canonical encoding, and of the snapshot module no longer name a class.

Tests:

- The snapshot fixtures `class()` and `network_class()` become
  `context()` and `network_context()`, the contexts of the same
  captures, and build their keys with `from_capture`; the fixtures of
  the capture and restore tests take them.
- The key's tests derive their keys from contexts, through
  `from_capture`, and change the contexts where they changed the class:
  `each_part_of_the_key_changes_it`,
  `a_generations_own_metadata_leaves_the_key_as_it_is`,
  `complete_capture_time_round_trips_without_changing_compatibility_identity`,
  `a_key_holds_what_its_capture_made`,
  `a_capture_that_does_not_match_its_class_is_refused`, which loses the
  case of a network whose policy attaches no NIC, since a context holds
  the NIC itself, `a_class_selects_a_profile_as_openvmm_does`,
  `keys_read_back_from_their_canonical_encoding`,
  `keys_with_the_removed_guest_build_field_are_refused`,
  `a_key_that_holds_its_network_s_lowering_after_its_invariants_is_refused`,
  `keys_of_machines_that_no_manifest_describes_are_refused`, and
  `the_conformance_vectors_decode_and_encode`, which loses the class
  vectors.
- `invalid_classes_are_refused` becomes
  `captures_of_invalid_contexts_are_refused`: the same invalid inputs,
  which `from_capture` refuses with the messages of the context's
  checks.
- Retired with the class: `the_guest_build_is_not_part_of_a_snapshot_key`
  and `each_field_of_a_class_changes_its_identity`, and the class's part
  of `identities_have_a_text_form`.
- `tests/vectors/snapshot-key-v1.txt` loses its `CLASS` vectors; its
  `KEY` vectors do not change.

Docs: the README's snapshot section and the vectors' README describe the
key alone. The public-API snapshots lose the class.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

`SandboxPlan`, the typed plan of a cold layered launch, with its
`SandboxDistro`, `SandboxUpper`, `SandboxNetwork`, `BlockRole` and
persistable form, and `SandboxLaunch` and `SandboxSettings`, the launch
of `nvx-rs sandbox` that made such a plan, served only the old launch
path and the tests: the CLI checks and launches a sandbox through its
`VmConfig`, and checks the command line that it launches since SL6.0f.

They go, with `PLAN_VERSION`, the profile's `KERNEL_COMMAND_LINE_MAX_SIZE`,
`OPENVMM_COMMAND_LINE_RESERVE` and `SANDBOX_COMMAND_LINE_MAX_SIZE`, the
workload limits (`PIDS_MAX_LIMIT` and the settings' checks), and
`options::validate_sandbox_systemd_policy`, the preflight of a
`SandboxLaunch`, whose two checks, `validate_sandbox_entrypoint` and
`DistroBinding::verify`, the CLI calls itself. The boot rendering of
shares goes too: `BootShares`, `boot_shares`, `aggregate_share_tokens`,
`aggregate_command_line_fragment`, `export_command_line_fragment`,
`aggregate_child_name`, `aggregate_child_argument`, `mount_argument`,
and the private `command_line_fragment` and bootstrap-token constants
of `mount`. `plan_mounts`, `plan_mounts_with` and `path_text` stay for

What only the CLI uses now allows `dead_code` without the `cli`
feature, as `spawn` does: `mount::check_distinct_export_roots` and its
re-export beside `HostQueries`, and `config::reject_container_path`.

Tests:

- `host::sandbox`'s own tests retire the plan's and the launch's cases:
  `launch_contract_builds_agent_command_line`,
  `launch_contract_rejects_duplicates_and_reserved_tokens`,
  `launch_settings_are_checked_in_order`,
  `launch_rejects_limits_the_guest_cgroup_cannot_store`,
  `launch_contract_attaches_mount_and_reserves_bootstrap_tokens`,
  `launch_contract_attaches_several_shares_as_an_aggregate`,
  `launch_bounds_shares_by_the_kernel_command_line` and
  `launch_contract_rejects_disk_option_delimiters_and_unbalanced_brackets`,
  whose refusal `config`'s tests and `tests/cli/validation.rs` keep.
  `launch_contract_attaches_a_file_as_an_aggregate_child` becomes
  `file_shares_take_no_policy_paths_or_reserved_targets`, its checks of
  shares without the rendering, and
  `launch_validation_requires_the_layers_and_the_scratch_image` becomes
  `missing_files_are_named_with_their_components_alone`, its check of
  `require_file`. The share checks plan their shares with `plan_mounts`
  and check the plan again as a start does, with
  `check_distinct_export_roots` and `ExportPlan::verify`:
  `launch_validation_rejects_overlapping_or_foreign_host_paths`,
  `shares_that_only_a_verbatim_path_names_are_refused`,
  `launch_validation_rejects_shares_that_came_to_overlap` and
  `launch_validation_requires_plain_mount_directory`. The fixtures
  `exported`, `deny`, `with_export` and `distro` go; `host_text` is
  Windows-only.
- The specification tests retire `aggregate_child_name_known_answer`,
  `launch_arguments_follow_the_openvmm_contract`,
  `accepted_launch_shapes_keep_their_arguments_and_kernel_tokens`,
  `shares_follow_the_openvmm_and_guest_contracts`,
  `launch_settings_follow_the_guest_contract`,
  `caller_parameters_follow_linux_and_guest_rules`,
  `aggregate_child_names_follow_the_restore_contract`,
  `kernel_command_line_stays_within_1024_bytes` and
  `reserved_kernel_tokens_are_always_refused`, which the CLI's tests of
  the command line that it launches cover. `layer_values_are_role_path_uuid`,
  `kernel_token_values_refuse_separators`,
  `the_reproduction_of_microsoft_nvx_723_is_refused` and
  `accepted_values_stay_one_kernel_parameter` keep their checks of
  layers and targets, and `canonical_layer_uuids_reach_the_guest`
  becomes `canonical_layer_uuids_round_trip`.
- The share tests retire `aggregate_child_names_pin_their_targets` and
  `boot_tokens_refuse_what_the_shell_cannot_bind`, and drop the boot
  rendering from `mount_parser_defaults_to_read_only_and_accepts_rw`,
  `mount_parser_accepts_host_paths_with_commas`,
  `mount_owner_defaults_to_vmm_and_forwards_caller`,
  `mount_access_policy_is_validated_and_forwarded` and
  `shares_are_planned_through_the_export_planner`.
- The option tests' preflight calls `validate_sandbox_entrypoint` and
  `DistroBinding::verify`, as the CLI does, in
  `distro_manifest_binds_the_layer`,
  `systemd_entrypoints_and_images_are_refused_independently`,
  `sandbox_allows_non_systemd_sbin_init`,
  `the_entrypoint_check_needs_no_manifest_and_precedes_the_distro_verification`,
  `sandbox_rejects_systemd_from_bound_distro_metadata` and
  `distro_manifests_are_strict_json`. Their shares give the export
  plan's OpenVMM arguments and kernel token, which
  `sandbox_command_shares_a_file` and
  `sandbox_command_attributes_mount_deny_to_the_preceding_mount` check.
- `cold_command_lines_keep_the_old_root_view_and_mapping_values`
  compared a configuration's command line with those of `LaunchSpec`
  and `SandboxPlan`. As
  `cold_command_lines_carry_the_root_the_view_and_the_mapping_count`,
  it checks the line against the configuration: the root's image and
  upper beside its other tokens, the view, and the mapping count.
- `tests/cli/openvmm.rs`'s `two_share_command_line_room` spells the
  tokens that OpenVMM appends for the shares.

Docs: the README's sandbox section and module row, "Images by path",
"Sandbox input contract", which describes the CLI's check of the command
line, and "Specification tests"; the case matrix row that named the
config test; the docs of `layer`, `mount`, the CLI's sandbox state and
the snapshot key. The public-API snapshots lose the deleted items.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

`host::launch`, the OpenVMM command line of a managed microVM that a
`LaunchSpec` described, with `VmmLaunch`, the inputs that it shared
with an adapter's launch, served only the old launch path and the
tests: `VmConfig` and `vm::create` render and check every launch, and
the CLI renders the guest's tokens.

The module goes whole: `LaunchSpec` with `check`, `kernel_command_line`,
`openvmm_arguments`, `vmm_launch` and `check_process_command_line`;
`VmmLaunch` with `RESERVE` and `arguments`; `WorkloadIdentity`'s
`DEFAULT` and `select`; `MAX_TIMEOUT`, `DEFAULT_MEMORY_MIB`,
`DEFAULT_HOSTNAME`, `base_command_line`, `kernel_parameters_problem`
and `timeout_problem`; and its re-exports of `host::config`'s
`COMMAND_LINE_BUDGET`, `DEFAULT_GUEST_NETWORK` and Windows command-line
helpers, which stay in `host::config`, as `OPENVMM_COMMAND_LINE_RESERVE`
does for `VmConfig::check_command_line`. `protocol::WORKLOAD_ACCOUNT_TOKEN`,
which only `LaunchSpec` rendered, goes too; the fake OpenVMM spells the
token itself.

What the deletion leaves unused goes with it: `host::sys::effective_ids`,
which only `WorkloadIdentity::select` called. `protocol`'s
`WorkloadIdentity`, which activation payloads carry, was public only
through `host::launch`, so it becomes `pub(crate)`, and `protocol`
re-exports its module only for the CLI and the guest, its remaining
users.

Tests: `host::launch`'s tests retire with it:
`kernel_command_line_sets_the_hostname`,
`arguments_select_the_managed_direct_guest`,
`mappings_add_the_export_and_the_mapping_count`,
`oversized_process_command_lines_are_rejected`,
`launches_may_use_the_reserve_that_provisioning_keeps`,
`every_launch_names_its_own_inputs_alike`,
`the_reserve_of_a_plan_holds_the_rest_of_a_launch_of_inputs_of_max_path`,
`kernel_parameters_are_checked`,
`kernel_parameters_are_read_as_the_kernel_reads_them`,
`reserved_parameters_are_refused_whatever_separates_them`,
`the_kernel_reads_the_hostname_after_accepted_parameters`,
`every_command_line_checks_the_specification`, `timeouts_are_bounded`
and `workloads_that_map_host_paths_take_the_host_identity`. `config`'s
tests keep checking the Windows command-line helpers. The restore
driver's test workload spells the identity that `DEFAULT` named.

Docs: the README loses `host::launch`'s section and module row, and
`host::config`'s part says what the helpers count; the docs of the
reserve and of `boot_arguments` no longer name the old planning. The
public-API snapshots lose the module and the token.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

The shell `/init` read the tokens that OpenVMM appends for its
`--microvm-lifecycle` and `--microvm-workload-identity` options,
`nvx_lifecycle=`, `nvx_workload_uid=` and `nvx_workload_gid=`, beside
the CLI's own, `nvx_mode=` and `nvx_identity=`, and handed a layered
root whose command line held `nvx_lifecycle=` to the older init agent,
`nvx-init-agent`. Since the old launch paths are gone, no launch of NVX
gives those tokens: the CLI names the lifecycle and the identity with
its own.

The init no longer reads the three tokens, and starts `nvx-init` for
every layered root, whose `nvx_exec=` it no longer runs either, as it
did not for a layered root without the token. A blockless guest takes
its lifecycle from `nvx_mode=` and its workload identity from
`nvx_identity=` alone.

The `workload-identity` and `managed-lifecycle` scenarios start OpenVMM
directly, with its options, which OpenVMM itself checks: they now also
give the CLI's tokens, `nvx_identity=` for each identity, and
`nvx_mode=managed nvx_identity=65534:65534`, so that the guest's init
selects what OpenVMM's options did.

Tests:

- `test_old_lifecycle_tokens_keep_the_old_layered_init` becomes
  `test_old_lifecycle_tokens_no_longer_select_the_old_layered_init`:
  the same layered roots start `nvx-init`.
- `test_old_workload_identity_tokens_name_no_identity` checks that a
  one-shot workload named only by `nvx_workload_uid=` and
  `nvx_workload_gid=` has no identity.
- `test_exec_override_cannot_bypass_the_new_sandbox_init` and
  `test_missing_helpers_or_selected_init_fail_without_fallback` expect
  `nvx-init` for a layered root with `nvx_lifecycle=managed`, and its
  failure when it is missing.
- The scenarios' unit tests,
  `test_workload_identity_scenario_checks_enforcement_and_rejection`
  and `test_managed_lifecycle_runs_the_nvx_rs_test_and_checks_what_it_leaves`,
  check the CLI's tokens on the command line.

Docs: the boot protocol says that `/init` ignores OpenVMM's identity and
lifecycle tokens, the guest-agent design that a layered root runs
`nvx-init`, and the project structure what `init` starts and that it no
longer starts the older sandbox scripts.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

Since the shell /init stopped reading OpenVMM's lifecycle and workload
tokens, OpenVMM's --microvm-workload-identity no longer names the
identity of a guest's workload, and a guest ignored it. OpenVMM's
documentation of that option asks the guest to fail closed when it
cannot apply the identity.

So /init fails closed. When the command line has OpenVMM's
nvx_workload_uid= or nvx_workload_gid=, a boot goes on only if
nvx_identity= names the same UID and GID. Otherwise /init stops with
NVX-WORKLOAD-ERROR and status 125 before it starts anything: an
nvx_exec= program, a one-shot or managed workload, the shares, or
nvx-init. It recognizes the two tokens only to refuse a mismatch: it
still takes the identity from nvx_identity= alone, and still ignores
nvx_lifecycle=. NVX's own launches don't change: the CLI and the
library pass no OpenVMM identity, and the scenarios that pass one also
pass the same nvx_identity=. A caller that launches OpenVMM directly
with --microvm-workload-identity adds nvx_identity= with the same
identity to its command line.

Docs: the boot protocol (5.1) says that /init fails closed on OpenVMM's
identity tokens, and the machine model (2.1.2) that NVX's launchers
name the workload identity and lifecycle with tokens of their own,
which the machine profile's tokens no longer select. The case matrix's
row of workload-identity names its new checks.

Tests: GuestInitRoutingTests' test_old_workload_identity_tokens_name_no_identity
becomes test_openvmm_workload_identity_needs_the_same_nvx_identity,
which refuses OpenVMM's identity without nvx_identity=, with its UID
alone, and with another nvx_identity=, on the nvx_exec, one-shot,
managed and sandbox routes, before anything starts, and lets the same
identity boot on. The workload-identity scenario boots twice more, with
OpenVMM's identity and no nvx_identity=, and with an nvx_identity= of
another identity, and requires both to fail closed with the refusal;
its unit tests check those boots, and that a guest that runs either
fails the scenario.

Part of #1122 (SL6.3).

Co-authored-by: Copilot <[email protected]>

Copilot AI left a comment