You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
doc: describe the implemented Ubuntu guest instead of its proposal - #453
doc/guests/ubuntu-guest.md (design chapter 7) was the pre-implementation proposal kept after the work landed: it was labeled Implemented but still read as a plan ("should", "will", phases, acceptance criteria, risks, and a to-do list of documentation changes), and several statements no longer matched the code. This PR rewrites it as a short, architecture-level description of the implemented Ubuntu initramfs and Ubuntu sandbox layer (844 → 191 lines), links to the Build, Run, usage, and distribution guides instead of repeating command details, and keeps the unimplemented full systemd guest as a Proposed section.
Only this file changes, so CI treats the PR as documentation-only. doc/design.md already links the chapter by the same path and title; no other document links into it.
Changes
Corrected statements:
Old statement
Now
Evidence
The kernel contains "the microVM LAPIC-frequency override"
Removed; the patches add only the xe9 consoles and shared virtio-mmio interrupt status
kernel/patches/ (0001–0003); bbc4040 dropped the LAPIC patch
The kernel "intentionally omits … module loading"
It enables module support only for strict module memory protection, ships no modules, and /init disables loading at boot
kernel/config-microvm (CONFIG_MODULES=y, CONFIG_STRICT_MODULE_RWX=y, no =m); guest/common/init (modules_disabled)
EROFS policy allows "file capabilities, ACLs, and security labels … through an explicit allowlist"
The layer rejects every extended attribute
scripts/nvx_tools/ubuntu.py metadata policy
Alpine "may also emit the generic marker"; Ubuntu emits the marker after the shell is ready (from /init)
Ubuntu's Bash startup file prints NVX-GUEST-BOOT-OK: ubuntu
guest/ubuntu/nvx-bashrc, guest/common/init
--guest all is valid for build commands
Only build-guest accepts all (dropped from the chapter; usage.md covers options)
Proposed CI coverage table ("Run … on KVM, MSHV, and WHP")
Actual coverage: smoke scenarios on every backend, broader scenarios on Linux/KVM, sandbox layer and live-share smoke on Linux backends, no performance gates
.github/workflows/run-nvx-microvm-tests.yml, ci.yml (KVM, MSHV, WHP callers); benchmark --help has no --guest
Newly stated, verified behavior: Alpine is the only sandbox control initramfs (guests.pysandbox_control, sandbox launcher uses the Alpine initramfs); the 512 MiB default (run --help); the supplemental package lock and its seven packages (ubuntu/packages.lock.json); the extractor's rejections and maintainer-action allowlist (ubuntu.py, build_constants.py); root customization and account checks (ubuntu.py); build-distro-layer accepts only --guest ubuntu, requires --replace to overwrite, and refuses /sbin/init or a systemd package (build.py); the EROFS UUID derivation (ubuntu.py); the workload's namespaces and privilege drop (guest/alpine/nvx-container-launch, nvx-container-enter); sandbox systemd rejection (scripts/nvx.py); manifest fields and release validation (ubuntu.py, release.py); verify checks the Ubuntu pin against SOURCE-MANIFEST.json (release.py); console-snapshot is rejected for Ubuntu (microvm_tests.py).
Removed as obsolete planning material: Decision/Motivation (condensed to one rationale paragraph), Goals/Non-goals, Implementation sequence, Acceptance criteria, Risks, Documentation changes, the stale "Last updated" header, and the speculative platform-independent guest bundle.
Conservative choices: kept the chapter at its current path and title so doc/design.md and readers' bookmarks stay valid; kept the 320 MiB minimum in doc/run.md and linked to it rather than restating it.
No OpenVMM design contract changed; pinned OpenVMM is 3796991d52ce07d88b5dba25e4d1e8deaff6fd95 (dev 75f5ba35f).
Follow-ups
doc/openvmm-upstream-roadmap.md is a point-in-time plan pinned to fork tip 2728f33e and upstream 1fd455b19 (2026-10-01); the OpenVMM pin has moved several times since. It needs a refresh or a clear "snapshot as of" label.
python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests — Ran 110 tests, OK (skipped=1).
Throwaway link checker (outside the repo) over the changed file and doc/design.md, which links to it: all relative links and anchors resolve, one H1, balanced code fences, and doc/design.md links every chapter in doc/design/ — OK.
git diff --check — clean.
python scripts\nvx.py verify — source tree and submodule metadata are consistent.
The Ubuntu guest chapter was the pre-implementation proposal, labeled
Implemented, with goals, phases, acceptance criteria, and a to-do list of
documentation changes. Several statements no longer matched the code: the
kernel no longer carries a LAPIC-frequency override, it enables module
support, the layer metadata policy rejects every extended attribute, the
Ubuntu boot marker comes from the Bash startup file, and only build-guest
accepts --guest all.
Rewrite it as an architecture-level description of the implemented
initramfs and sandbox layer, link to the build, run, usage, and
distribution guides for commands, and keep the full systemd guest as a
Proposed section.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Document shared IPC namespace in sandbox isolation boundary
doc/guests/ubuntu-guest.md:146
The launcher uses unshare --mount --pid --uts (guest/alpine/nvx-container-launch:16), so the workload shares the guest's IPC namespace as well as its network namespace. Because this paragraph defines the sandbox isolation boundary, omitting shared IPC can make the boundary appear stronger than it is; include it in the shared list.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
documentationImprovements or additions to documentation
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Pedro Henrique Penna (ppenna)
added
the
documentation
Summary
doc/guests/ubuntu-guest.md(design chapter 7) was the pre-implementation proposal kept after the work landed: it was labeled Implemented but still read as a plan ("should", "will", phases, acceptance criteria, risks, and a to-do list of documentation changes), and several statements no longer matched the code. This PR rewrites it as a short, architecture-level description of the implemented Ubuntu initramfs and Ubuntu sandbox layer (844 → 191 lines), links to the Build, Run, usage, and distribution guides instead of repeating command details, and keeps the unimplemented full systemd guest as a Proposed section.Only this file changes, so CI treats the PR as documentation-only.
doc/design.mdalready links the chapter by the same path and title; no other document links into it.Changes
Corrected statements:
kernel/patches/(0001–0003); bbc4040 dropped the LAPIC patch/initdisables loading at bootkernel/config-microvm(CONFIG_MODULES=y,CONFIG_STRICT_MODULE_RWX=y, no=m);guest/common/init(modules_disabled)scripts/nvx_tools/ubuntu.pymetadata policy/init)NVX-GUEST-BOOT-OK: ubuntuguest/ubuntu/nvx-bashrc,guest/common/init--guest allis valid for build commandsbuild-guestacceptsall(dropped from the chapter; usage.md covers options)python scripts/nvx.py build-initramfs --help,build-guest --help.github/workflows/run-nvx-microvm-tests.yml,ci.yml(KVM, MSHV, WHP callers);benchmark --helphas no--guestNewly stated, verified behavior: Alpine is the only sandbox control initramfs (
guests.pysandbox_control, sandbox launcher uses the Alpine initramfs); the 512 MiB default (run --help); the supplemental package lock and its seven packages (ubuntu/packages.lock.json); the extractor's rejections and maintainer-action allowlist (ubuntu.py,build_constants.py); root customization and account checks (ubuntu.py);build-distro-layeraccepts only--guest ubuntu, requires--replaceto overwrite, and refuses/sbin/initor asystemdpackage (build.py); the EROFS UUID derivation (ubuntu.py); the workload's namespaces and privilege drop (guest/alpine/nvx-container-launch,nvx-container-enter); sandbox systemd rejection (scripts/nvx.py); manifest fields and release validation (ubuntu.py,release.py);verifychecks the Ubuntu pin againstSOURCE-MANIFEST.json(release.py);console-snapshotis rejected for Ubuntu (microvm_tests.py).Removed as obsolete planning material: Decision/Motivation (condensed to one rationale paragraph), Goals/Non-goals, Implementation sequence, Acceptance criteria, Risks, Documentation changes, the stale "Last updated" header, and the speculative platform-independent guest bundle.
Conservative choices: kept the chapter at its current path and title so
doc/design.mdand readers' bookmarks stay valid; kept the 320 MiB minimum indoc/run.mdand linked to it rather than restating it.No OpenVMM design contract changed; pinned OpenVMM is
3796991d52ce07d88b5dba25e4d1e8deaff6fd95(dev75f5ba35f).Follow-ups
doc/openvmm-upstream-roadmap.mdis a point-in-time plan pinned to fork tip2728f33eand upstream1fd455b19(2026-10-01); the OpenVMM pin has moved several times since. It needs a refresh or a clear "snapshot as of" label.scripts/setup/README.mdis documentation outsidedoc/. Moving it is not documentation-only for CI (scripts/test_nvx_tools.pyclassifies it as an OpenVMM-suite input), and the docs that link to it (doc/ci.md,doc/setup.md) are in open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405 and Adopt bind-once microVM image slots #406.THIRD_PARTY_NOTICES.mdwas flagged in doc: document contribution standards and public OpenVMM access #448's review as still describing OpenVMM as private; it is outside this run's editable paths.doc/design/machine-and-device-abi.mdstill requires writable scratch while OpenVMMf12dcf5e8permits a scratchless RAM overlay for cold boot; that file is in open PRs test-microvm: pause and resume a microVM through OpenVMM state control #405, Adopt bind-once microVM image slots #406, and Support filesystem-only streamed microVM snapshots #417.Validation
python -m unittest scripts.test_nvx_tools.CliTests scripts.test_performance.PerformanceTests— Ran 110 tests, OK (skipped=1).doc/design.md, which links to it: all relative links and anchors resolve, one H1, balanced code fences, anddoc/design.mdlinks every chapter indoc/design/— OK.git diff --check— clean.python scripts\nvx.py verify— source tree and submodule metadata are consistent.