Skip to content

guest: switch into a layered root once - #1295

Merged
Pedro Henrique Penna (ppenna) merged 1 commit into
feature/nvx-refactorfrom
esaurez/slim-2.4.1-sl7.1b-20261103
Nov 6, 2026
Merged

Pedro Henrique Penna (ppenna) merged 1 commit into
feature/nvx-refactorfrom
esaurez/slim-2.4.1-sl7.1b-20261103

Conversation

@esaurez

@esaurez Enrique Saurez (esaurez) commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

Part of #1104: SL7.1b. Rebased onto feature/nvx-refactor after #1276
was squash-merged. Only this pull request's own commit was replayed; its
patch is unchanged.

What changes

Add the crate-private Root::switch and SwitchError in the hidden
guest::root reference implementation. An init can make its assembled root
/ once for the whole VM:

  • Open the root's directory descriptor before moving its mount onto / with
    MS_MOVE, then reuse the descriptor-based chroot and change directory to
    /. A failed move leaves teardown available.
  • Once the move succeeds, record an irreversible switched state separate from
    the failure latch. A second switch and teardown refuse, and dropping the
    root unmounts nothing, including when entering the moved root fails.
  • Keep SourceRoot and TargetRoot descriptors opened before the switch
    usable for later mappings. Required descriptors remain the caller's job.

The switch stays crate-private until nvx-init calls it in #1115, with the
prescribed dead-code expectation. SwitchError and
TeardownError::is_switched stay crate-private too. The latter recognizes
teardown refusal through its empty failure list, preserving the size of errors
that nest TeardownError. The getter documentation states that Root::path
keeps returning the original mount-point path after switching.

There is no new caller, reversible switch, per-execution behavior change,
runtime-mount redesign, VM view operation, crate, or public error contract.
The public-API snapshots are unchanged. The restack preserves the parent's
runtime attachment ownership and rollback changes.

Size

64 core lines in 4 production files: root.rs (57), root/kernel.rs (5),
sys/mod.rs (1), and sys/spawn.rs (1). Including the test-layout allowlist's
one policy line, the raw measurement is 65 core lines in 5 files, below the
issue's 400-line stop.

Tests

Add four fake-kernel tests in guest::root::tests::switch:
a_root_switches_once_and_its_teardown_then_unmounts_nothing,
a_switched_root_that_is_dropped_unmounts_nothing,
a_move_that_fails_leaves_the_root_unswitched, and
a_root_whose_entry_fails_has_switched.

Add the privileged
guest::root::tests::privileged::a_switched_root_keeps_its_mounts_and_maps_through_earlier_descriptors.
It switches in a thread with its own root and working directories, checks the
new root and earlier mapping, maps another file through previously opened
descriptors, and checks that teardown and drop leave every mount.

All 115 existing tests listed below are kept, with their bodies unchanged;
none is renamed or retired. check_test_changes.py --base d8f1e45d reports
four existing-test changes:

  • guest::root::kernel::tests::Operation gains EnterRoot for failure
    injection, and Call gains the corresponding recorded operation.
  • The privileged fixture's Scene::root initializes switched to false.
  • The test-layout allowlist permits the switch's additional
    cfg_attr(not(test), expect(dead_code, ...)) hook in root.rs; its future
    caller removes that expectation and hook.
The 115 kept tests
guest::root::tests::
  assembly_mounts_the_image_and_the_scratch_under_the_overlay
  devices_are_found_when_they_appear_and_missing_ones_time_out
  an_assembly_waits_for_its_devices_until_its_deadline_at_the_latest
  a_device_of_another_size_is_refused_before_it_is_flushed
  the_expected_uuid_is_checked_in_the_superblock_before_the_mount
  a_failed_assembly_unmounts_what_it_mounted_and_reports_what_stays
  a_runtime_directory_that_the_overlay_options_reserve_is_refused
  a_runtime_directory_whose_path_is_not_canonical_is_refused
  a_root_mounts_nothing_through_a_symbolic_link
  new_upper_and_work_directories_have_mode_0755_whatever_the_umask
  a_fresh_upper_s_directories_must_be_missing_or_empty
  the_freshness_check_takes_one_entry_of_a_directory_and_opens_none
  a_runtime_directory_that_another_root_holds_is_refused
  a_runtime_directory_where_a_file_system_is_mounted_is_refused
  the_kernel_finds_its_mount_points
  the_kernel_shows_a_mount_s_options
  a_thread_with_private_tables_finds_its_mount_points_and_options
  a_mount_s_options_are_the_last_field_of_its_line_in_the_mount_table
  a_runtime_directory_where_a_directory_is_bound_is_refused
  a_gpt_disk_s_layers_are_mounted_under_the_overlay_top_first
  both_overlay_modes_assemble_on_both_uppers_with_their_own_option_sets
  a_tmpfs_upper_needs_no_scratch_device
  a_refused_option_set_fails_without_a_fallback
  an_overlay_that_the_kernel_mounts_without_its_mode_in_effect_is_refused_and_unmounted
  options_that_the_kernel_does_not_show_have_their_defaults
  effective_options_that_cannot_be_read_fail_the_assembly
  overlay_options_that_a_mount_cannot_pass_are_refused_before_any_mount
  up_to_195_layers_fit_in_the_overlay_s_options_below_run_nvx
  the_journal_policy_is_checked_in_the_scratch_s_superblock_before_any_mount
  a_device_whose_access_mode_is_not_its_role_s_is_refused_before_it_is_flushed
  a_tmpfs_upper_is_unmounted_last_and_every_failure_reported
  a_scratch_s_file_system_is_synced_right_before_its_unmount
  a_scratch_whose_sync_fails_stays_mounted_and_the_failure_is_reported
  a_gpt_disk_that_differs_from_the_expected_identities_is_refused_before_any_mount
  a_gpt_disk_without_a_layer_is_refused_before_any_mount
  a_layer_that_is_not_ext4_or_whose_journal_needs_a_recovery_is_refused_before_any_mount
  a_missing_partition_fails_at_once_before_any_mount
  a_reread_asks_the_kernel_for_the_distro_disk_s_table_once_the_device_appears
  the_kernel_rereads_a_partition_table_that_changed_under_it
  the_first_partition_is_returned_as_opaque_bytes_within_its_bound
  a_teardown_unmounts_the_layers_top_first_and_reports_every_failure
  a_layer_that_a_failed_unmount_left_keeps_the_runtime_directory_occupied
  what_a_share_s_target_lacks_is_created_with_its_mode_whatever_the_umask_or_a_default_acl
  shares_are_mounted_restricted_and_torn_down_first_in_reverse_order
  refused_shares_mount_nothing
  a_root_has_one_aggregate_and_one_that_failed_part_of_the_way_latches_it
  a_child_whose_restriction_fails_is_never_attached
  a_child_that_the_aggregate_lacks_or_holds_as_another_kind_binds_nothing
  a_failed_unmount_is_reported_and_the_later_ones_still_attempted
  a_share_through_a_link_or_onto_another_mount_is_refused_and_latches_the_root
  a_share_or_a_mapping_that_a_rename_moved_and_that_stays_is_the_teardown_s
  mappings_apply_beneath_the_overlay_in_order_and_go_first_at_the_teardown
  a_root_in_run_nvx_mounts_the_host_export_where_its_boot_token_names_it
  the_host_export_is_mounted_out_of_the_root_and_unmounted_after_its_mappings
  a_refused_tag_creates_and_mounts_nothing_and_a_failed_export_latches_the_root
  the_host_export_is_mounted_through_no_symbolic_link
  a_hostfs_directory_that_is_there_already_must_be_private
  a_dropped_root_is_torn_down_once
  bootstrap_moves_every_process_but_kernel_threads_and_applies_the_resources
  bootstrap_mounts_the_hierarchy_unless_the_parent_is_a_cgroup
  bootstrap_names_the_failed_step_and_keeps_the_earlier_changes
  bootstrap_accepts_a_missing_sysctl_only_without_user_namespaces
  bootstrap_fails_while_a_process_keeps_returning_to_the_parent
  bootstrap_succeeds_when_the_last_pass_empties_the_parent
guest::root::tests::runtime::
  the_runtime_s_file_systems_are_mounted_in_order_once_the_tree_is_restricted
  without_a_time_status_nothing_is_bound_at_run_nvx_time
  a_failed_mount_unmounts_what_the_call_mounted
  a_failed_restriction_mounts_nothing_and_other_failed_steps_undo_the_call
  a_mount_point_through_a_symbolic_link_or_with_a_mount_already_is_refused
  a_mount_that_the_undo_fails_to_unmount_stays_for_the_teardown
  a_runtime_mount_that_moves_is_detached_before_it_is_recorded
  a_runtime_mount_whose_detach_fails_is_owned_until_teardown
  a_time_status_bind_that_moves_and_cannot_detach_stays_owned_until_teardown
  a_time_status_bind_whose_lookup_and_detach_fail_reports_its_teardown_failure
  a_call_after_a_share_a_child_or_a_mapping_is_refused_before_it_changes_anything
  shares_and_mappings_beneath_run_after_the_runtime_are_on_its_tmpfs_and_unmounted_first
  a_run_that_the_mapper_fails_to_add_latches_the_root_and_one_that_an_undo_left_is_its_own
guest::root::tests::privileged::
  the_runtime_s_file_systems_have_an_execution_s_options_nodes_and_links
  a_call_that_fails_part_of_the_way_unmounts_what_it_mounted
  a_call_after_a_mapping_is_refused_and_leaves_it_reachable
  mappings_beneath_run_after_the_runtime_are_on_its_tmpfs_and_go_with_it
guest::mappings::mapper::tests::
  mappings_are_restricted_copies_attached_in_order
  targets_are_created_with_their_modes_whatever_the_umask
  targets_are_created_with_their_modes_whatever_a_default_acl
  zero_mappings_do_no_work
  links_at_any_component_are_refused
  a_component_that_is_not_a_directory_is_refused
  sources_and_targets_must_be_of_one_kind
  targets_are_created_only_on_the_root_s_own_mounts
  targets_that_would_shadow_a_mapping_or_a_mount_are_refused
  a_mapping_covers_the_root_of_a_mount_that_the_root_owns
  reserved_targets_and_their_ancestors_are_refused
  the_first_failure_latches_the_mapper
  a_failure_at_any_step_leaves_nothing_mounted
  a_mapping_that_a_rename_moved_is_detached_and_refused
  what_a_rename_puts_in_the_place_of_a_created_component_keeps_its_mode
  a_teardown_unmounts_in_reverse_order_and_reports_each_failure
  a_runtime_bind_skips_the_checks_of_a_host_mapping_but_not_the_walk
  runtime_binds_unbind_in_reverse_order_and_report_each_failure
  a_staged_mount_moves_onto_its_target_with_its_restrictions
  a_target_root_is_the_root_of_a_mount_of_a_whole_file_system
  mappings_name_paths_below_their_roots
  an_empty_source_maps_the_source_root_itself_from_beneath_it
  errors_name_what_failed
guest::mappings::mapper::tests::privileged::
  a_target_root_shows_its_whole_file_system
  links_and_magic_links_at_every_component_are_refused
  a_rename_race_never_mounts_outside_the_target
  kinds_nested_targets_and_reserved_targets_are_checked
  an_empty_source_maps_a_copy_of_the_source_root_s_own_mount
  a_mapping_covers_the_root_of_a_mount_only_if_the_root_owns_it
  a_workload_that_is_not_root_enters_what_a_mapper_created_whatever_the_umask_or_a_default_acl
  a_read_only_mapping_is_never_visible_writable
  a_teardown_unmounts_each_mapping_and_reports_a_busy_one
  a_thread_with_a_descriptor_table_of_its_own_tears_its_mappings_down
guest::sys::spawn::tests::
  a_child_enters_its_root_or_reports_why_not

Validation

Qualification uses source 203891ffe84626a584947e71a787c29119417936,
on the exact feature-branch parent
d8f1e45d14dce3b525f958f52d7895b8ba2ac840, the squash merge of #1276.
Earlier 4d5d7463 or pinned-256ebe3d results are not this commit's
qualification.

The target subsequently advanced to 3d243e59. A nonmutating Git merge
analysis is conflict-free; that integrated tree is not claimed as tested.

  • Rust, Windows and Linux: all applicable check-nvx-rs commands passed:
    rustfmt, the five warning-denied Clippy feature sets, all/default/no-feature
    tests and the no-feature build, synthetic bundling with NVX_BUNDLE unset,
    warning-denied rustdoc, MSRV 1.89, and OpenVMM vector/CPU-profile comparisons.
    The complete Linux all-feature command used serialized libtest fixtures;
    assertions, test selection and timeouts were unchanged.

  • Linux-only Rust: the macOS check, both public-API snapshots, guest-binary
    lint/tests, guest-profile build, exact source digest, static-ELF checks, and
    the 39 guest-tool integration tests passed. All runtime-adapter action
    commands passed in protocol-only/host-only configurations on both systems
    and in the static musl guest-only configuration on Linux.

  • Quality: every applicable Linux check-quality command passed,
    including pinned shell-linter images, both Pyright platforms, Markdown links,
    test layout, kernel configuration, all 25 Specula tests, and PowerShell
    syntax. The quality action is Linux-only.

  • CLI, both systems: complete runs each reported 1814 tests and OK,
    with 67 platform skips on Windows and 35 on Linux.
    The canceled-capture shell test executed successfully. Both adversarial
    runs reported 84 tests (11 Linux-only skips on Windows); all four
    host-profile tests and every action help command passed.

  • Independent review: no remaining findings at this exact head.

  • Native runtime, WHP and MSHV: all five privileged root tests actually
    executed on each backend, including the switch-and-retained-descriptor test,
    with no skipped cases. All six selected microVM scenarios and teardown passed
    with one processor: managed-exec-config, sandbox-lifecycle,
    sandbox-proxy-only, sandbox-ram-upper, private-network-ingress, and
    time-abi-conformance. The normal canonical adapter driver reported all
    156 scenarios across 11 targets passed on each backend, using source- and
    hash-bound precompiled executables. Windows used one libtest thread; its
    concurrent-clone assertions were unchanged. Consumed input hashes were
    unchanged after all runs, and the post-run lifecycle guards passed.

The host CLI was built from this commit on each system. Alpine/Ubuntu
initramfses, Rust guest executables and the Ubuntu layer were built from this
commit's source. Their guest-source digest is
613df803bf776e2e88ecc9ee7ae99424ebe708c976998afc8d3ffae5b53650e6.
Both native VMMs match the inherited OpenVMM revision
14dc4116ec7e57567633c4b7b07892aca3a58522. The WHP VMM was built locally
from that clean revision. The MSHV VMM is a checksum- and provenance-verified
native input from v0.1.0-dev.4cfe8330e719; none of that release's guest
images or host CLIs was used as candidate proof. The kernel 6.18.38 input from
v0.1.0-dev.256ebe3dd9c2 still matches this commit's kernel build inputs.
The runtime and Ubuntu source-provenance validators passed.

Environment corrections touched no tests, assertions or timeouts: native
CPython 3.14.9 and Git's usr/bin/sh on Windows; private Linux PID/mount
namespaces with a reaping Bash PID 1; isolated retained temporary fixtures;
and restored tool prerequisites. Interrupted Linux attempts were not counted:
after recovering space in inactive, owned build targets, each complete
affected action command was rerun successfully. Only owned build-output
permissions and provenance placement were corrected. Read-only shared
artifacts were not changed. After the three successful Linux VM commands, an
unprivileged process-inventory postflight lacked access; the read-only inventory
was repeated with the runtime's normal privilege and confirmed cleanup. The
failed outer launcher is retained separately, not counted as a passing test
command.

KVM was not run locally. The group's full default and multi-distribution
microVM matrix remains for its final pull request and CI.

@esaurez Enrique Saurez (esaurez) added the tests-modified Changes existing tests, test data, or test wiring label Nov 5, 2026
@github-actions

github-actions Bot commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

This pull request changes existing tests

It modifies or removes 4 existing test asset(s), listed below. Review each with care: a change to a test can hide a regression that the test caught. See doc/contribute.md#changes-to-existing-tests.

Test code

Change What Before After
modified helper enum Operation in guest::root::kernel::tests nvx-rs/src/guest/root/kernel/tests.rs:29 nvx-rs/src/guest/root/kernel/tests.rs:29
modified helper enum Call in guest::root::kernel::tests nvx-rs/src/guest/root/kernel/tests.rs:71 nvx-rs/src/guest/root/kernel/tests.rs:74
modified helper fn root in guest::root::tests::privileged, impl Scene`` nvx-rs/src/guest/root/tests/privileged.rs:76 nvx-rs/src/guest/root/tests/privileged.rs:80

Test policy

Change What Before After
loosened allowlist entry nvx-rs/src/guest/root.rs (the seams allow 2 test hooks, up from 1) scripts/test-layout-allowlist.json

Relocated unchanged: 0; added: 12. Compared the merge base d8f1e45d14dc with 203891ffe846.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the internal layered-root switch.

No open issues 🎉

What changed in this PR

Adds a one-time layered-root switch to NVX’s internal guest implementation for the future nvx-init caller in #1115, completing the SL7.1b step of #1104 without changing the public API.

Changes:

  • Adds crate-private Root::switch, moving the root mount onto / and entering it through an open descriptor.
  • Tracks switched state so repeat switches and teardown refuse, while dropping the root preserves its mounts.
  • Adds fake-kernel and privileged tests covering failure handling, mount preservation, and mappings through pre-switch descriptors.
File Description
scripts/​test-layout-allowlist.json Allows the temporary dead-code expectation’s additional test hook.
nvx-rs/​src/​guest/​sys/​spawn.rs Makes the existing descriptor-based root-entry helper crate-visible.
nvx-rs/​src/​guest/​sys/​mod.rs Re-exports the root-entry helper internally.
nvx-rs/​src/​guest/​root/​tests/​switch.rs Adds four tests for switching, failures, and mount preservation.
nvx-rs/​src/​guest/​root/​tests/​privileged.rs Tests real root switching and mappings through retained descriptors.
nvx-rs/​src/​guest/​root/​tests.rs Registers the switch test module.
nvx-rs/​src/​guest/​root/​kernel/​tests.rs Adds root-entry recording and failure injection to the fake kernel.
nvx-rs/​src/​guest/​root/​kernel.rs Adds root entry to the kernel interface and system implementation.
nvx-rs/​src/​guest/​root.rs Implements switching, switched-state guards, and error reporting.
nvx-rs/​README.md Documents switching behavior and privileged test coverage.

Review effort: Balanced

@esaurez
Enrique Saurez (esaurez) force-pushed the esaurez/slim-2.4.1-sl7.1a-20261103 branch 2 times, most recently from 423fed0 to e4d4bca Compare November 5, 2026 23:28
@esaurez
Enrique Saurez (esaurez) force-pushed the esaurez/slim-2.4.1-sl7.1b-20261103 branch from 9d8fa14 to 4d5d746 Compare November 6, 2026 00:18
@esaurez
Enrique Saurez (esaurez) requested a balanced review from Copilot November 6, 2026 00:19

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

The crate-private root-switch change has no active review issues.

No open issues 🎉

Review effort: Balanced

Base automatically changed from esaurez/slim-2.4.1-sl7.1a-20261103 to feature/nvx-refactor November 6, 2026 05:01
Part of #1104.

Move the assembled root onto /, enter it through a descriptor opened
before the move, then change the working directory to the new root.
Once the mount moves, refuse another switch and teardown and leave all
mounts in place when the root is dropped, even if entering it fails.

Keep the switch crate-private until nvx-init calls it. Cover the
irreversible state and failures with the kernel seam, and preserve
mappings through descriptors opened before a real root switch.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 0a2abff7-0f1b-453d-80eb-f9e7f2daefaf

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the crate-private, one-time layered-root switch.

No open issues 🎉

Review effort: Balanced

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

Labels

feat-nvx-refactor tests-modified Changes existing tests, test data, or test wiring

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants